{"id":29175920,"url":"https://github.com/egoroof/browser-id3-writer","last_synced_at":"2025-07-01T16:12:03.324Z","repository":{"id":48524427,"uuid":"48021388","full_name":"egoroof/browser-id3-writer","owner":"egoroof","description":"JavaScript library for writing ID3 tag to MP3 files in browsers and Node.js","archived":false,"fork":false,"pushed_at":"2025-01-26T22:19:07.000Z","size":2458,"stargazers_count":188,"open_issues_count":4,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-22T18:54:48.957Z","etag":null,"topics":["browser","id3","javascript","library","nodejs","tag","writer"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/egoroof.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-15T05:22:06.000Z","updated_at":"2025-05-27T04:44:40.000Z","dependencies_parsed_at":"2024-04-06T11:29:56.064Z","dependency_job_id":"b08d7df2-04af-4ea3-a78b-257f27aa8f49","html_url":"https://github.com/egoroof/browser-id3-writer","commit_stats":{"total_commits":277,"total_committers":11,"mean_commits":"25.181818181818183","dds":0.3790613718411552,"last_synced_commit":"6d29a0608c97d40964d5c77370266f6e8bcd35a6"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/egoroof/browser-id3-writer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/egoroof%2Fbrowser-id3-writer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/egoroof%2Fbrowser-id3-writer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/egoroof%2Fbrowser-id3-writer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/egoroof%2Fbrowser-id3-writer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/egoroof","download_url":"https://codeload.github.com/egoroof/browser-id3-writer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/egoroof%2Fbrowser-id3-writer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262996821,"owners_count":23396910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","id3","javascript","library","nodejs","tag","writer"],"created_at":"2025-07-01T16:12:01.986Z","updated_at":"2025-07-01T16:12:03.317Z","avatar_url":"https://github.com/egoroof.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Browser ID3 Writer\n\n[![npm package][npm-badge]][npm]\n\n[npm-badge]: https://img.shields.io/npm/v/browser-id3-writer.svg?style=flat-square\n[npm]: https://www.npmjs.com/package/browser-id3-writer\n\nJavaScript library for writing [ID3 (v2.3)](https://egoroof.github.io/browser-id3-writer/spec/) tag to MP3 files in browsers and Node.js.\nIt can't read the tag so use another lib to do it.\n\n**Note**: the library removes existing ID3 tag (v2.2, v2.3 and v2.4).\n\nHere is an online demonstration: [egoroof.github.io/browser-id3-writer/](https://egoroof.github.io/browser-id3-writer/)\n\nFind the changelog in [CHANGELOG.md](https://github.com/egoroof/browser-id3-writer/blob/master/CHANGELOG.md)\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [JS modules](#js-modules)\n- [Usage](#usage)\n  - [Browser](#browser)\n    1. [Get ArrayBuffer of song](#get-arraybuffer-of-song)\n    2. [Add a tag](#add-a-tag)\n    3. [Save file](#save-file)\n    4. [Memory control](#memory-control)\n  - [Node.js](#nodejs)\n- [Supported frames](#supported-frames)\n- [APIC picture types](#apic-picture-types)\n- [SYLT content types](#sylt-content-types)\n- [SYLT timestamp formats](#sylt-timestamp-formats)\n\n## Installation\n\nTake latest version [here](https://unpkg.com/browser-id3-writer) or with npm:\n\n```\nnpm install browser-id3-writer --save\n```\n\n### JS modules\n\nThe library is only deployed in [native JS modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), so in browsers you have to use `script` with type `module`:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { ID3Writer } from 'https://your-host/browser-id3-writer.mjs';\n  // your code here..\n\u003c/script\u003e\n```\n\nOr bundle the library to your code.\n\nIn Nodejs it imports easily:\n\n```js\nimport { ID3Writer } from 'browser-id3-writer';\n```\n\n## Usage\n\n### Browser\n\n#### Get ArrayBuffer of song\n\nIn browsers you should first get\n[ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)\nof the song you would like to add ID3 tag.\n\n##### FileReader\n\nFor example you can create file input and use\n[FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader):\n\n```html\n\u003cinput type=\"file\" id=\"file\" accept=\"audio/mpeg\" /\u003e\n\u003cscript type=\"module\"\u003e\n  import { ID3Writer } from 'https://your-host/browser-id3-writer.mjs';\n\n  document.getElementById('file').addEventListener('change', function () {\n    if (this.files.length === 0) {\n      return;\n    }\n    const reader = new FileReader();\n    reader.onload = function () {\n      const arrayBuffer = reader.result;\n      // go next\n    };\n    reader.onerror = function () {\n      // handle error\n      console.error('Reader error', reader.error);\n    };\n    reader.readAsArrayBuffer(this.files[0]);\n  });\n\u003c/script\u003e\n```\n\n##### Fetch\n\nTo get arrayBuffer from a remote server you can use\n[Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API):\n\n```js\nconst request = await fetch(urlToSongFile);\nif (!request.ok) {\n  // handle error\n  console.error(`Unable to fetch ${urlToSongFile}`);\n}\nconst arrayBuffer = await request.arrayBuffer();\n// go next\n```\n\n#### Add a tag\n\nCreate a new `ID3Writer` instance with arrayBuffer of your song, set frames and add a tag:\n\n```js\n// arrayBuffer of song or empty arrayBuffer if you just want only id3 tag without song\nconst writer = new ID3Writer(arrayBuffer);\nwriter\n  .setFrame('TIT2', 'Home')\n  .setFrame('TPE1', ['Eminem', '50 Cent'])\n  .setFrame('TALB', 'Friday Night Lights')\n  .setFrame('TYER', 2004)\n  .setFrame('TRCK', '6/8')\n  .setFrame('TCON', ['Soundtrack'])\n  .setFrame('TBPM', 128)\n  .setFrame('WPAY', 'https://google.com')\n  .setFrame('TKEY', 'Fbm')\n  .setFrame('APIC', {\n    type: 3,\n    data: coverArrayBuffer,\n    description: 'Super picture',\n  });\nwriter.addTag();\n```\n\n#### Save file\n\nNow you can save it to file as you want:\n\n```js\nconst taggedSongBuffer = writer.arrayBuffer;\nconst blob = writer.getBlob();\nconst url = writer.getURL();\n```\n\nFor example you can save file using [FileSaver.js](https://github.com/eligrey/FileSaver.js/):\n\n```js\nsaveAs(blob, 'song with tags.mp3');\n```\n\nIf you are writing chromium extension you can save file using\n[Downloads API](https://developer.chrome.com/docs/extensions/reference/api/downloads):\n\n```js\nchrome.downloads.download({\n  url: url,\n  filename: 'song with tags.mp3',\n});\n```\n\n#### Memory control\n\nWhen you generate URLs via `writer.getURL()` you should know\nthat whole file is kept in memory until you close the page or move to another one.\nSo if you generate lots of URLs in a single page you should manually free memory\nafter you finish downloading file:\n\n```js\nURL.revokeObjectURL(url); // if you know url or\nwriter.revokeURL(); // if you have access to writer\n```\n\n### Node.js\n\nSimple example with blocking IO:\n\n```js\nimport { ID3Writer } from 'browser-id3-writer';\nimport { readFileSync, writeFileSync } from 'fs';\n\nconst songBuffer = readFileSync('path_to_song.mp3');\nconst coverBuffer = readFileSync('path_to_cover.jpg');\n\nconst writer = new ID3Writer(songBuffer);\nwriter\n  .setFrame('TIT2', 'Home')\n  .setFrame('TPE1', ['Eminem', '50 Cent'])\n  .setFrame('TALB', 'Friday Night Lights')\n  .setFrame('TYER', 2004)\n  .setFrame('APIC', {\n    type: 3,\n    data: coverBuffer,\n    description: 'Super picture',\n  });\nwriter.addTag();\n\nconst taggedSongBuffer = Buffer.from(writer.arrayBuffer);\nwriteFileSync('song_with_tags.mp3', taggedSongBuffer);\n```\n\nYou can also create only ID3 tag without song and use it as you want:\n\n```js\nconst writer = new ID3Writer(Buffer.alloc(0));\nwriter.padding = 0; // default 4096\nwriter.setFrame('TIT2', 'Home');\nwriter.addTag();\nconst id3Buffer = Buffer.from(writer.arrayBuffer);\n```\n\n## Supported frames\n\n**array of strings:**\n\n- TPE1 (song artists)\n- TCOM (song composers)\n- TCON (song genres)\n\n**string**\n\n- TLAN (language)\n- TIT1 (content group description)\n- TIT2 (song title)\n- TIT3 (song subtitle)\n- TALB (album title)\n- TPE2 (album artist)\n- TPE3 (conductor/performer refinement)\n- TPE4 (interpreted, remixed, or otherwise modified by)\n- TRCK (song number in album): '5' or '5/10'\n- TPOS (album disc number): '1' or '1/3'\n- TPUB (label name)\n- TKEY (initial key)\n- TMED (media type)\n- TDAT (album release date expressed as 'DDMM')\n- TSRC (isrc - international standard recording code)\n- TCOP (copyright message)\n- TCMP (iTunes compilation flag)\n- TEXT (lyricist / text writer)\n- WCOM (commercial information)\n- WCOP (copyright/Legal information)\n- WOAF (official audio file webpage)\n- WOAR (official artist/performer webpage)\n- WOAS (official audio source webpage)\n- WORS (official internet radio station homepage)\n- WPAY (payment)\n- WPUB (publishers official webpage)\n\n**integer**\n\n- TLEN (song duration in milliseconds)\n- TYER (album release year)\n- TBPM (beats per minute)\n\n**object**\n\n- COMM (comments):\n\n```js\nwriter.setFrame('COMM', {\n  description: 'description here',\n  text: 'text here',\n  language: 'eng',\n});\n```\n\n- USLT (unsychronised lyrics):\n\n```js\nwriter.setFrame('USLT', {\n  description: 'description here',\n  lyrics: 'lyrics here',\n  language: 'eng',\n});\n```\n\n- IPLS (involved people list):\n\n```js\nwriter.setFrame('IPLS', [\n  ['role', 'name'],\n  ['role', 'name'],\n  // ...\n]);\n```\n\n- SYLT (synchronised lyrics):\n\n```js\nwriter.setFrame('SYLT', {\n  type: 1,\n  text: [\n    ['lyrics here', 0],\n    ['lyrics here', 3500],\n    // ...\n  ],\n  timestampFormat: 2,\n  language: 'eng',\n  description: 'description',\n});\n```\n\n`text` is an array of arrays of string and integer.\n\n- TXXX (user defined text):\n\n```js\nwriter.setFrame('TXXX', {\n  description: 'description here',\n  value: 'value here',\n});\n```\n\n- PRIV (private frame):\n\n```js\nwriter.setFrame('PRIV', {\n  id: 'identifier',\n  data: dataArrayBuffer,\n});\n```\n\n- APIC (attached picture):\n\n```js\nwriter.setFrame('APIC', {\n  type: 3,\n  data: coverArrayBuffer,\n  description: 'description here',\n  useUnicodeEncoding: false,\n});\n```\n\n`useUnicodeEncoding` should only be `true` when description contains non-Western characters.\nWhen it's set to `true` some program might not be able to read the picture correctly.\nSee [#42](https://github.com/egoroof/browser-id3-writer/issues/42).\n\n## APIC picture types\n\n| Type | Name                                |\n| ---- | ----------------------------------- |\n| 0    | Other                               |\n| 1    | 32x32 pixels 'file icon' (PNG only) |\n| 2    | Other file icon                     |\n| 3    | Cover (front)                       |\n| 4    | Cover (back)                        |\n| 5    | Leaflet page                        |\n| 6    | Media (e.g. label side of CD)       |\n| 7    | Lead artist/lead performer/soloist  |\n| 8    | Artist/performer                    |\n| 9    | Conductor                           |\n| 10   | Band/Orchestra                      |\n| 11   | Composer                            |\n| 12   | Lyricist/text writer                |\n| 13   | Recording location                  |\n| 14   | During recording                    |\n| 15   | During performance                  |\n| 16   | Movie/video screen capture          |\n| 17   | A bright coloured fish              |\n| 18   | Illustration                        |\n| 19   | Band/artist logotype                |\n| 20   | Publisher/Studio logotype           |\n\n## SYLT content types\n\n| Type | Name                                         |\n| ---- | -------------------------------------------- |\n| 0    | Other                                        |\n| 1    | Lyrics                                       |\n| 2    | Text transcription                           |\n| 3    | Movement/part name (e.g. \"Adagio\")           |\n| 4    | Events (e.g. \"Don Quijote enters the stage\") |\n| 5    | Chord (e.g. \"Bb F Fsus\")                     |\n| 6    | Trivia/'pop up' information                  |\n\n## SYLT timestamp formats\n\n| Type | Name                                                    |\n| ---- | ------------------------------------------------------- |\n| 1    | Absolute time, 32 bit sized, using MPEG frames as unit  |\n| 2    | Absolute time, 32 bit sized, using milliseconds as unit |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fegoroof%2Fbrowser-id3-writer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fegoroof%2Fbrowser-id3-writer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fegoroof%2Fbrowser-id3-writer/lists"}