|
| 1 | +node-taglib-sharp / [Exports](modules.md) |
| 2 | + |
| 3 | +# TagLib# for Node |
| 4 | + |
| 5 | +| Master | Develop | Latest | |
| 6 | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 7 | +| [](https://ci.appveyor.com/project/benrr101/node-taglib-sharp/branch/master) | [](https://ci.appveyor.com/project/benrr101/node-taglib-sharp/branch/develop) | [](https://ci.appveyor.com/project/benrr101/node-taglib-sharp) | |
| 8 | +| [](https://coveralls.io/github/benrr101/node-taglib-sharp?branch=master) | [](https://coveralls.io/github/benrr101/node-taglib-sharp?branch=develop) | [](https://coveralls.io/github/benrr101/node-taglib-sharp) | |
| 9 | + |
| 10 | +## Description |
| 11 | +TagLib# is a .NET library that has been around for years. It provides a unified interface for |
| 12 | +accessing metadata from a vast selection of media files. Until now there hasn't been a port of this |
| 13 | +library for Node.js. This project is a mostly wholesale translation of the original TagLib#. |
| 14 | + |
| 15 | +Note: A port of TagLib already exists for Node.js. Despite TagLib being the origin of TabLib#, it |
| 16 | +is substantially lacking in the variety of media formats that can be handled. TagLib# greatly |
| 17 | +improved on the original TagLib, hence why this project exists. |
| 18 | + |
| 19 | +## Supported Tagging Formats |
| 20 | +* [APE](http://wiki.hydrogenaud.io/index.php?title=APE_key): `AAC`, `APE`, `FLAC`, `M2A`, `MP1`, `MP2`, `MP3` |
| 21 | +* [ASF](https://docs.microsoft.com/en-us/windows/win32/wmformat/overview-of-the-asf-format): `ASF`, `WMA`, `WMV` |
| 22 | +* DIVX: `AVI`, `DIVX`, `WAV` |
| 23 | +* [ID3v1](https://id3.org/ID3v1): `AAC`, `FLAC`, `M2A`, `MP1`, `MP2`, `MP3` |
| 24 | +* [ID3v2](https://id3.org/Developer%20Information): `AAC`, `AIF`, `AIFF`, `AVI`, `DIVX`, `FLAC`, `M2A`, `MP1`, `MP2`, `MP3`, `WAV` |
| 25 | +* [Matroska/WebM](https://www.matroska.org/technical/tagging.html): `MK3D`, `MKA`, `MKS`, `MKV`, `WEBM` _read-only_ |
| 26 | +* MovieID: `AVI`, `DIVX`, `WAV` |
| 27 | +* [RIFF Info](https://www.exiftool.org/TagNames/RIFF.html#Info): `AVI`, `DIVX`, `WAV` |
| 28 | +* [Xiph Comment](https://www.xiph.org/vorbis/doc/v-comment.html): `FLAC`, `OGA`, `OGG`, `OGV`, `OPUS` |
| 29 | +* ... More coming soon |
| 30 | + |
| 31 | +## Supported File Formats |
| 32 | +* Advanced Audio Codec (AAC): `AAC` |
| 33 | +* Advanced Systems Format (ASF): `ASF`, `WMA`, `WMV` |
| 34 | +* Audio Interchange Format (AIFF): `AIF`, `AIFF` |
| 35 | +* Free Lossless Audio Codec (FLAC): `FLAC` |
| 36 | +* Matroska: `MK3D`, `MKA`, `MKS`, `MKV` |
| 37 | +* MPEG-1/2 Audio: `M2A`, `MP1`, `MP2`, `MP3` |
| 38 | +* MPEG-1/2 Video: `M2V`, `MPE`, `MPEG`, `MPG`, `MPV2` |
| 39 | +* Monkey's Audio: `APE` |
| 40 | +* Ogg: `OGA`, `OGG`, `OGV`, `OPUS` |
| 41 | +* Resource Interchange File Format (RIFF): `AVI`, `DIVX`, `WAV` |
| 42 | +* WebM: `WEBM` |
| 43 | +* ... More coming soon |
| 44 | + |
| 45 | +## Installation |
| 46 | +``` |
| 47 | +npm install --save node-taglib-sharp |
| 48 | +``` |
| 49 | + |
| 50 | +## Getting Started |
| 51 | +Getting started with node-taglib-sharp is surprisingly easy. The main entry point into the library |
| 52 | +is via the `File` class. |
| 53 | + |
| 54 | +```typescript |
| 55 | +import {File} from "node-taglib-sharp"; |
| 56 | + |
| 57 | +const myFile = File.createFromPath("path/to/my/file.mp3"); |
| 58 | +``` |
| 59 | + |
| 60 | +The `File` class provides factory methods for generating instances of classes that inherit from |
| 61 | +`File` to provide implementation specific to a file format (such as `ApeFile` providing support |
| 62 | +for Monkey's Audio files). The `File` class has exposes the `properties` and `tag` properties to |
| 63 | +allow manipulation of the tagging information and reading audio/video properties. |
| 64 | + |
| 65 | +See the docs for [the File class](docs/classes/File.md) for complete details of the |
| 66 | +available properties. |
| 67 | + |
| 68 | +```typescript |
| 69 | +console.log(myFile.properties.audioBitrate); |
| 70 | +console.log(myFile.tag.title); |
| 71 | +``` |
| 72 | + |
| 73 | +The `Tag` base class provides a tagging-format agnostic interface to modify tag(s) on the file |
| 74 | +object. Set tag properties as needed and they will be stored in a tagging format that is supported |
| 75 | +by the file type. The changes can be easily written back to the file with `save()`. |
| 76 | + |
| 77 | +See the docs for [the Tag class](docs/classes/Tag.md) for complete details of the fields |
| 78 | +supported by the format-agnostic `Tag` class. |
| 79 | + |
| 80 | +```typescript |
| 81 | +myFile.tag.title = "Time Won't Let Me Go"; |
| 82 | +myFile.tag.album = "The Sun And The Moon"; |
| 83 | +myFile.tag.performers = ["The Bravery"]; |
| 84 | +myFile.save(); |
| 85 | +myFile.dispose(); |
| 86 | +``` |
| 87 | + |
| 88 | +## Known Issues |
| 89 | +* Maximum supported file size is 8192TB |
| 90 | + - Why is this an issue? 8192TB is yuuuuge, but .NET implementation supports 8192PB file sizes. |
| 91 | + - The Node.js 12 [fs](https://nodejs.org/docs/latest-v12.x/api/fs.html) library only supports |
| 92 | + `integer` types for position arguments, which safely goes up to `2^52 - 1`. Node 15 supports |
| 93 | + `number` or `biginteger` for position arguments which would increase supported sizes to 64-bit |
| 94 | + integers. Please create issue if this is a blocker. |
0 commit comments