Skip to content

03 Default Tags

Jump to bottom
Benjamin Russell edited this page Jul 8, 2023 · 1 revision

Introduction

Every file type has a set of tags that it supports. Some file formats only support one type of tag, such as ASF files that only support ASF tags. Some file formats support more than one type of tag. In the latter case, you may not want your files to have multiple tags, or perhaps you want your file to have every tagging format possible for maximum compatibility. In either situation, you may want to configure the default tags for a tagging type.

Default tags are the tags that are created when a file is loaded. If the file does not have the configured default tag type, a new one is created. Unlike TagLib#, the default tags can be configured.

An Example w/Untagged Files

Let's say I want to tag an untagged MP3 file. I know that an MP3 file supports ID3v1, ID3v2, and APE tags, and the default tags are ID3v1 and ID3v2. Let's see what tags are in the file.

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

const myFile = File.createFromPath("path/to/myFile.mp3");
console.log(myFile.tagTypesOnDisk); // 0 -> TagTypes.None
console.log(myFile.tagTypes);       // 6 -> TagTypes.Id3v1 | TagTypes.Id3v2

As you can see, even though the file does not have any tags as it sits on the disk, we still have tags to play with. ​

Changing Default Tags

Let's say I really hate ID3v1 tags (I really do) and I never want new ones created when I'm manipulating my metadata. I'd really prefer all my files to have APE tags by default. Fortunately, you can easily configure the default tags.

import {File, MpegAudioFileSettings, TagTypes} from "node-taglib-sharp";

MpegAudioFileSettings.defaultTagTypes = TagTypes.Ape;

const myFile = File.createFromPath("path/to/myFile.mp3");
console.log(myFile.tagTypesOnDisk); // 0 -> TagTypes.None
console.log(myFile.tagTypes);       // 8 -> TagTypes.Ape;

After making the changes to the config and reloading the file, I can now see that my file has an APE tag.

Note: Configuration changes must be made before opening a file. If configuration changes happen after a file is loaded, the file should be closed and reopened.

Where Should My Tag Go?

For some file types, certain tag types can be placed at the beginning or end of a file. In this library, these files are referred to as "sandwich" files because tags "sandwich" the media like two slices of bread sandwiching the meaty goodness inside of your sandwich. (see Advanced Tagging for more details) Although flexible, this presents a conundrum: should the default tags go at the beginning or end of the file?

For sandwich files, and for the tag types that allow it, you can configure which end of the file default tags are stored on. In this example, let's say I prefer APE tags to go at the beginning of the file and ID3v2 tags to go at the end (there's no good reason to prefer this other than it makes a good example).

import {File, MpegAudioFile, MpegAudioFileSettings, TagTypes} from "node-taglib-sharp";

MpegAudioFileSettings.defaultTagTypes = TagTypes.Id3v2 | TagTypes.Ape;
MpegAudioFileSettings.preferApeTagsAtFileEnd = false;
MpegAudioFileSettings.preferId3v2TagsAtFileEnd = true;

const myFile = File.createFromPath("path/to/myFile.mp3");
console.log(myFile.tagTypesOnDisk); // 0  -> TagTypes.None
console.log(myFile.tagTypes);       // 12 -> TagTypes.Id3v2 | TagTypes.Ape 

const myMp3File = <MpegAudioFile> myFile;
console.log(myMp3File.tag.startTag.tagTypes); // 8 -> TagTypes.Ape
console.log(myMp3File.tag.endTag.tagTypes);   // 4 -> TagTypes.Id3v2

As expected, we still have no tags on disk and ID3v2 and APE tags in memory. However, if we peer into the start and end tag collections (this is covered in more detail in Advanced Tagging), we can confirm that the APE tag goes at the start of the file and the ID3v2 tags go at the end of the file - just like we configured!

Note: It is not supported to add the same tag type at both ends of a file. Also, some tag types may only be stored at one end of a file.

Files With Tags

Unless your file is brand new, it's fairly likely you'll already have tags in your file. How do default tags work in that case? Let's look at an example:

import {File, MpegAudioFileSettings, TagTypes} from 'node-taglib-sharp';

console.log(MpegAudioFileSettings.defaultTagTypes);                    // 6 -> TagTypes.Id3v1 | TagTypes.Id3v2

const myTaggedFile = File.createFromPath("path/to/myId3v2TaggedFile.mp3");
console.log(myTaggedFile.tagTypesOnDisk);                          // 4 -> TagTypes.Id3v2
console.log(myTaggedFile.tagTypes);                                // 6 -> TagTypes.Id3v1 | TagTypes.Id3v2

console.log(myTaggedFile.getTag(TagTypes.Id3v2, false).isEmpty()); // false
console.log(myTaggedFile.getTag(TagTypes.Id3v1, false).isEmpty()); // false

As you can see, any default tag type that doesn't exist is created when the file is loaded. The existing tags are copied into the new tag, as well.

What About ... No ... Default Tags?

Ok, hotshot, you can have no default tags. However, there's a caveat: Some file types will always have a File.tag object and it cannot be removed. However, just because it exists does not always mean that there's storage behind the object. For instance:

import {File, MpegAudioFileSettings, TagTypes} from "node-taglib-sharp";

MpegAudioFileSettings.defaultTagTypes = TagTypes.None;
const myFile = File.createFromPath("path/to/my/file.mp3");
console.log(myFile.tagTypesOnDisk); // 0 -> TagTypes.None
console.log(myFile.tagTypes);       // 0 -> TagTypes.None

myFile.tag.title = "foo";
console.log(myFile.tag.title); // nothing

In this case, the File.tag object is a SandwichTag that doesn't contain any tags yet. Any tag properties you write to that tag will not be stored.

In other cases File.tag will be undefined. In this situation, attempting to write tag properties will throw an error:

import {File, AiffAudioFileSettings, TagTypes} from "node-taglib-sharp";

AiffAudioFileSettings.defaultTagTypes = TagTypes.None;
const myFile = File.createFromPath("path/to/my/file.aiff");
console.log(myFile.tagTypes); // 0 -> TagTypes.None
console.log(myFile.tag);      // undefined
myFile.tag.title = "foo";     // ERROR!

Before writing to a tag, you should either leave defaults turned on or check File.tagTypes to make sure there are tags in memory that can hold your changes. This definitely muddies the waters and was a situation that having default tags was meant to resolve. However, sometimes you just need to have fine tune control of your tags. Make sure to read up in Advanced Tagging to explore the world of micro-managing tags.

This situation is currently in flux and may be changed in a future major release, please feel free to provide input or suggestions

A Couple More Notes

  • Any file type that supports "No Tags" will have a *FileSettings class where defaultTagTypes can be set. See Tagging Support Table for which tags support "no tags".
  • The tags that exist on memory haven't been written to disk. You have to call File.save() to write them to disk.
Clone this wiki locally