This library is used inside DaPlayer to read or set tags of audio files. This is mostly just a wrapper around TagLib.
This library is not released directly on NPM, you should rather check it out locally or reference a GitHub URL like a branch or a tar-ball:
{
"daplayer-tagging": "https://github.com/daplayer/tagging"
}
Then run yarn install
to download it.
This library reads and set tags in a synchronous way. It comes with two
handy methods: get
and set
.
Important note: This project is usable in any of your project but since it's
mainly intented to be used inside DaPlayer, it can only deal with absolute paths
so don't expect it to automatically expand paths such as ../folder/audio.mp3
.
Reading audio tags is fairly easy but the returned result may not be what you would expect.
Actually, you need to create an instance of Tagging.Library
and call the get
method on it to get tags of some audio files. For example:
const Tagging = require('daplayer-tagging');
var library = new Tagging.Library();
library.get([
'/path/to/artist/album/track.mp3',
'/path/to/artist/single.mp3',
'/path/to/lonely_single.mp3'
]);
Inspecting the library
, you will get something like this:
{
artists: {
darius: {
name: 'Darius',
albums: {
Velour: [
{
title: 'Maliblue',
artist: 'Darius',
genre: 'French House',
track: 4,
id: '/path/to/artist/album/track.mp3',
// ...
}
]
},
singles: [{title: 'Pyor', /* ... */}]
}
},
singles: [
{ title: 'Pyor', artist: 'Darius', /* ... */ },
{ title: 'Cherokee - Take Care of You', /* ... */ }
]
}
Here is a couple things to keep in mind dealing with this result:
- Each artist is stored under a key which is a lower-cased version of their name. This avoids having two entries for the same artist if their musics are tagged with a different case (e.g. "Bring Me the Horizon" and "Bring Me The Horizon").
- The singles are both attached to their artist and stored under the
singles
key as DaPlayer treats singles as a single collection.
The id
field actually refers to the given path; this is a cheap way to have
an unique identifier for each record.
It is also possible to get the cover arts of audio files passing a path to
a folder which will contain the images. Then the icon
attribute of each
record will be filled automatically. For instance:
library.get(files, '/path/to/covers/folder');
Actually the name of the image file is a CRC checksum of the image's data.
It is not possible to have access to any sort of Base64 string of the picture's data since this would take too much memory. You can fork this project and change this behavior if storing cover files inside a folder is not what you want.
Finally, the get
method accepts, as the second or third argument, a callback to
know the current progression processing all the given files as this may be long when
the array gets large. For example:
library.get(files, function(index, total) {
console.log((index / total) * 100);
});
Since reading huge folders may take time, you should rather cache the library
somewhere to avoid reprocessing files each time. If you still hold a reference
to the library in memory, it's totally fine to do several get
calls but
if you are loading the library from a JSON file for instance, you can instantiate
a library from a hash like this:
var library = new Tagging.Library({
artists: { /* */ },
singles: [ /* */ ]
});
If you are watching for changes inside a folder or you've cached the library and
you want to remove elements from it, it ships with a remove
method that takes
an array of files to remove and will remove every occurrences of the files inside
singles and albums:
library.remove([
'/path/to/file.mp3',
'/path/to/file2.mp3'
]);
You can also define audio tags through this library very easily with the set
method. You just need to pass it a path to the audio file and an object with
the fields you want to define.
You don't need to know the underlying name of the frames, you can use the same
as the one returned by get
to erase them:
const Tagging = require('daplayer-tagging');
Tagging.set('/path/to/audio/file.mp3', {
title: 'Born In Winter',
artist: 'Gojira',
album: 'L\'enfant sauvage',
genre: 'Death Metal',
track: 10,
icon: '/path/to/image.jpg'
});
Contributing to this project is fairly easy. To set it up, you are done with the following steps:
$ git clone https://github.com/daplayer/tagging daplayer-tagging
$ cd daplayer-tagging
$ yarn install
$ make
make
will actually compile the project and run all the tests.
Copyright (c) 2016-2017, Robin Dupret
This project is a wrapper around the TagLib library which is available either under the terms of the LGPL or the MPL license.
This project is available under the terms of the MPL license. You can check out the LICENSE file for further information.