Skip to content

01 Getting Started

Jump to bottom
Benjamin Russell edited this page Jul 8, 2023 · 3 revisions

Welcome

Welcome to the node-taglib-sharp wiki! The goal of these pages are to provide some guidance on how you can use the node-taglib-sharp library in your code.

Introduction

If you're completely new here, node-taglib-sharp is a node.js library that allows you to manipulate metadata (tags) for a wide variety of media files. This information can be information such as track titles, artist, director, attached cover art, or codec information.

A long time ago, the TagLib project was created with the intention of being a one stop shop for all your media tagging needs. It was written in C++ and although powerful, only supported audio files. The Mono project took on porting TagLib to C# and created TagLib#. In addition to porting all the original supports, they also added support for tagging video files and a wide variety of photo formats. I had created a few projects that leveraged TagLib# and was content with the features it offered. This project is a port of TagLib# for use in node.js

The biggest question I assume people are asking is "why create this?" To answer this, let's go back a few years. I was starting a new project that would present media files on one side and TV/movie databases on the other side to merge them (why I created that one is a totally different question). Since the project used electron, I looked for a multi-featured tagging library like the TagLib# I was used to. Although I found a couple ports of the original TagLib for node, they were simple wrappers around the C++ code. This meant I had to compile the C++ and that I was limited to the audio-only features that TagLib offered. Seeing there wasn't a node port of TagLib#, I decided I'd make the port myself.

Getting Started

node-taglib-sharp provides two mechanisms to manipulate the tagging data:

  • Unified Tagging
  • Advanced Tagging

In either case, start by adding the library to your project:

npm install --save node-taglib-sharp

Unified Tagging

Unified tagging is the easiest way to set tags on a media file. There are many different tagging formats (eg, APE, ID3v2) and different file formats (eg, MP3, FLAC) support either different tagging formats or utilize them differently. For instance, ID3v2 can be used in AVI files, but it is stored completely differently than in an MP3. To make dealing with all these possibilities simple, use the File class as a unified representation of a media file.

Load Your File

import {File} from "node-taglib-sharp";

const myFile = File.createFromPath("path/to/my/file.mp3");

Now you have a representation of the file you wish to tag. From there, you'll want to explore the two main properties of the File class:

console.log(myFile.properties.audioBitrate);
console.log(myFile.tag.title);

It's important to note that loading a file will automatically create default tags so there is always a place for your tag data to be stored. For more information on default tags, see [Default Tags](Default Tags).

Tag Your File

Now that you have a file and a unified tag to play with, you can update your tags! Although your file may have various tag formats, you can use the tag property of your file to change them all at once without worrying about internal implementation.

myFile.tag.title = "Time Won't Let Me Go";
myFile.tag.album = "The Sun And The Moon";
myFile.tag.performers = ["The Bravery"];

You'll note that some tag properties may not be singular as you might expect. For instance, performers and genre are string[]s rather than a single value. See the docs for the Tag class for reference.

It's important to note, as well, that if the tagging formats in a file don't support a particular field, setting the property will do nothing. You will encounter this if you try to set an amazonId on an ID3v1 tag, for example. The value will simply be thrown away. [This preserves the behavior of TagLib# but future releases may enable configuring throwing on setting unsupported fields].

Attach Pictures

After adding some tagging data, you might want to attach the cover art for the album to your file. This can also be done in a unified manner. Simply load your file from disk, add it to the pictures property of the tag, and you're all set!

// Make sure to add an import for the Picture class
import {Picture} from "node-taglib-sharp";

const myPicture = Picture.fromPath("path/to/my/picture.jpg");
myFile.tag.pictures = [myPicture];

Pictures also expose a unified interface for accessing information about them for the purposes of tagging. See the Picture class docs for more details. For more discussion on how to use Pictures, see Pictures.

Clearing/Removing Tags

If for some reason you want to remove all the data in your tags, this is easily done with clear():

myFile.tag.clear();

However, saving your file in this state will leave empty tags in the file. If you really want to blow away the tags in a file, use removeTags(types):

// You'll want to import the enum for TagTypes
import {TagTypes} from "node-taglib-sharp";

myFile.removeTags(TagTypes.AllTags);

You can also use removeTags to remove specific tags or groups of them. This is an advanced technique discussed in [Advanced Tagging](Advanced Tagging).

Saving Your File

Once you've made all the changes to your file you want to make, you'll need to save and dispose the file.

myFile.save();
myFile.dispose();

And that's it! Couldn't be easier to read tags, write them, and access codec information about your media!

Advanced Tagging

The unified tagging interface provides any easy way to access common tags that a media file might have. But certain tagging formats may expose format-specific fields you really want to access. Or you might have a program that reads non-standard tags. In those situations, you'll want more control over your tags. node-taglib-sharp exposes access to the lower level objects for just this purpose. Explaining it all in the getting started guide would probably be documentation overload, so check out [Advanced Tagging](Advanced Tagging) for more information.

Clone this wiki locally