{"id":42357698,"url":"https://github.com/rstemmer/id3edit","last_synced_at":"2026-01-27T16:36:46.636Z","repository":{"id":170258010,"uuid":"142592937","full_name":"rstemmer/id3edit","owner":"rstemmer","description":"🛠 id3edit is a command line tool to edit and debug ID3v2 tags of mp3 files supporting Unicode.","archived":false,"fork":false,"pushed_at":"2024-12-01T15:47:47.000Z","size":649,"stargazers_count":33,"open_issues_count":14,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-01T16:30:41.265Z","etag":null,"topics":["id3-parser","id3-writer","id3editor","id3v2","id3v2-3","id3v2-tag","mp3-tags"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rstemmer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","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":"2018-07-27T15:16:01.000Z","updated_at":"2024-12-01T15:46:53.000Z","dependencies_parsed_at":"2023-10-26T09:33:30.322Z","dependency_job_id":null,"html_url":"https://github.com/rstemmer/id3edit","commit_stats":null,"previous_names":["rstemmer/id3edit"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/rstemmer/id3edit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstemmer%2Fid3edit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstemmer%2Fid3edit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstemmer%2Fid3edit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstemmer%2Fid3edit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstemmer","download_url":"https://codeload.github.com/rstemmer/id3edit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstemmer%2Fid3edit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28816563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["id3-parser","id3-writer","id3editor","id3v2","id3v2-3","id3v2-tag","mp3-tags"],"created_at":"2026-01-27T16:36:46.557Z","updated_at":"2026-01-27T16:36:46.620Z","avatar_url":"https://github.com/rstemmer.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch3 align=\"center\"\u003eid3edit\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n  Status: 🟢  Active - License: GPL v3\n\u003c/div\u003e\n\n---\n\n\u003cp align=\"center\"\u003eid3edit is a command line ID3v2 tag editor and debugger\n    \u003cbr/\u003e\n\u003c/p\u003e\n\n![Print all frames with details](screenshots/02.jpg?raw=true)\n\n```bash\n# Install clang and zlib\npacman -S clang zlib # Use the package manager of your distribution\n\n# Install libprinthex\ngit clone https://github.com/rstemmer/libprinthex.git\ncd libprinthex\n./build.sh\nsudo ./install.sh # Installs to /usr/local/{lib,include}\n\n# Install id3edit\ngit clone https://github.com/rstemmer/id3edit.git\ncd id3edit\n./build.sh\nsudo ./install.sh # Installs to /usr/local/bin\n\nid3edit --readonly --showheader --get-all --get-frames bugtrigger.mp3\n```\n\n## Features\n\n`id3edit` is a command line editor to edit and **debug** ID3v2 tags ([ID3v2.3.0](http://id3.org/id3v2.3.0) \u0026 [ID3v2.4.0](http://id3.org/id3v2.4.0-structure) of mp3 files with full Unicode support.\n\nI separated id3edit from the [MusicDB Project](https://github.com/rstemmer/musicdb) to give it its own repository and own issue tracker.\n\n**Its main features are:**\n\n * Show all frames of the ID3 tag (colloquial \"mp3 tags\")\n * Get/Add/Edit specific frames (see [Name Definitions](#name-definitions))\n * Get/Add artworks (Support for jpeg and png. Create an issue if you need more types.)\n * Remove frames or the whole tag\n * Print hex-dump of a specific frame\n * You can overwrite the input file or write to a new path\n * It is made to handle invalid tags and headers and debug them\n * Can print a detailed list of all frames with comments when they are invalid\n * Supports Unicode correctly!\n * It works from command line\n * Support for ID3v2.3.0 (most common) and ID3v2.4.0 (latest)\n * All encodings supported (ISO 8859-1, UTF-16 with BOM, UTF-16BE, UTF-8)\n * Partial support of extended header: CRC feature supported!\n\n**Execution environment:**\n\n * Linux\n * MacOS\n    * Ported by [Slava Baryshnikov (SeventyB)](https://github.com/SeventyB)\n * BSD\n    * Ported by [Joel Demacky (tr0pe)](https://github.com/tr0pe)\n * Docker\n    * Maintained by [Hendri Kurniawan (hckurniawan)](https://github.com/hckurniawan)\n    * Dockerfile: [github.com/hckurniawan/docker-id3edit](https://github.com/hckurniawan/docker-id3edit)\n    * Image: [hub.docker.com](https://hub.docker.com/r/hckurniawan/id3edit)\n\n\n## Limitations\n\n * See Issue Tracker\n\n## Name Definitions\n\n * **Tag:** The whole ID3 meta data of an mp3 file is called the Tag. A tag can have multiple _frames_.\n * **Frame:** A Frame is one piece of information of the audio file. For example the name of the song.\n * **[ID3] Tag Header:** A _Tag_ consists of a header followed by multiple _frames_.\n * **Frame Header:** Each _frame_ consists of a header and the information encoded in the frame. This information itself can have a further header. For example text frames start with a byte defining the encoding of the text.\n\n## History of id3edit\n\nThe last three points form the feature list are the reason I developed this tool.\nIn the year 2013 I wanted to unify all tags of my music collection.\nTherefore I need an ID3 editor I can call from a script to automate the tagging process.\nFurthermore they had to be able to use Unicode encoded string (Think of Japanese bands).\nI only found only a few editors that were able to work with Unicode at all.\nOnly one of them provided a command line interface.\nThis tool complete messed up all my tags because the promised Unicode support did not work.\n\nThat's why I needed a \"ID3 Debugger\" and this project was born.\n\nLessons learned: Also backup huge data collection and test foreign tools properly before using it in scripts :)\n\nAfter separating id3edit from [MusicDB](https://github.com/rstemmer/musicdb) I reviewed the whole code and added some missing features.\nFurthermore I added ID3v2.4.0 support.\nSo version 2.0.0 of id3edit was born.\n\n## Examples\n\nHere are some everyday examples as well as an example of how to fix a broken ID3 tag.\n\n### Getting And Setting Frames\n\nThe following example first gets the name of audio file _example.mp3_, then changes its name to _\"Example Song Name\"_.\n\n```bash\nid3edit --get-name example.mp3\nid3edit --set-name \"Example Song Name\" example.mp3\n```\n\nTo write into a new file, you can use the `--outfile` option.\nIf all other meta data shall be removed use the `--clear` option.\nThe following example creates a clean set of meta data for a song file:\n\n```bash\nid3edit --set-name    \"Example Song\"         \\\\\n        --set-album   \"Example Album\"        \\\\\n        --set-artist  \"Example Artist\"       \\\\\n        --set-artwork ~/pictures/example.jpg \\\\\n        --set-genre   \"Example Genre\"        \\\\\n        --set-release 2018                   \\\\\n        --set-track   \"13/42\"                \\\\\n        --set-cd      \"1/1\"                  \\\\\n        --clean                              \\\\\n        --encoding    utf-8                  \\\\\n        --outfile Example\\ Song.mp3          \\\\\n        sourcefile.mp3\n\n# Review changes\nid3edit --get-all Example\\ Song.mp3\n```\n\n\n### Debugging\n\nFollowing scenario: The meta data of a song stored in an ID3 tag is invalid.\nAs an example I use a song from the band [Hämatom](https://en.wikipedia.org/wiki/H%C3%A4matom).\nThe file was originally tagged by a tool that claimed to support Unicode. As we discover in this section, this was not true :)\n\n#### Printing the meta data\n\n![Print all meta data](screenshots/01.jpg?raw=true)\n\n * `--get-all` prints all relevant frames.\n\nObviously there are some encoding problems and two different release dates.\nWe will look at the song name (`TIT2` frame) and genre (`TCON` frame) in detail later.\n\n#### Getting details of the damaged frames\n\nNow we can use `id3edit` to further inspect the file to figure out what's wrong:\n\n![Print all frames with details](screenshots/02.jpg?raw=true)\n\n * `--showheader` prints lots of details of the ID3 header and the frame headers while reading the ID3 Tag.\n * `--get-frames` prints a list of all available frames including details of their size and encoding as well as other useful information.\n    * The first column checks if the frames are defined or deprecated in the specific ID3v2 standard.\n    * Gray IDs are IDs that are not directly supported by _id3edit_. (When they start with a `T` we can work with them anyway)\n    * When there is a problem with the UTF-16 encoding, it gets mentioned in yellow.\n    * If there is an artwork embedded, details like the mime type and dimension of the image are displayed.\n\nThe result of this first look into the details give us the following information:\n\n 1. There is a frame not fully supported by _id3edit_ (`TSSE`). That's why they do not appear in the result of `--get-all`. (This is not a problem)\n 2. The `TDRC` frame is not defined in ID3v2.3.0 version of the standard that is defined by the header.\n 3. The claimed size of the ID3 Tag is greater than the actual size. The size given in the ID3 Tag Header will be adjusted. This must not be a sign of an invalid Tag. ID3 allows padding bytes that get striped away by _id3edit_.\n 4. There are two BOMs (Byte Order Marks) in the `TCON` frame. This is an indicator that the mp3 file was tagged by a software that is not ID3v2 conform and/or has problems with Unicode encoded data. It also explains why the genre name in the first screenshot looks so strange.\n 5. The artworks width is shorter than its height. That's just ugly but not really a problem with the ID3 Tag itself.\n\n#### Check and repair song name\n\n\nFirst lets check whats wrong with the song name (`TIT2`):\n\n![Hex dump of song title](screenshots/03.jpg?raw=true)\n\n * `--dump $FRAMEID` print a hex dump of a specific frame\n\nThe previous analysis using `--get-framelist` told us, that the `TIT2` frame should have been _ISO 8859-1_ (also called _Latin-1_ or falsely _ASCII_) encoded.\nThis gets indicated by the first byte of the text frame (0x00 = ISO 8859-1). \nThe actual text is _UTF-8_ encoded.\nThat is why the bytes 0xC3 and 0xA4 are interpreted as individual characters which is valid for the _ISO 8859-1_ encoding standard.\nAll other characters are correct because the have the same values in _UTF-8_ they have in _ISO 8859-1_.\n\nThe invalid frame can simply be fixed by calling `id3edit --set-name \"Stay Kränk\" invalid.mp3`.\n\n\n#### Check the TCON problem\n\nJust for demonstration lets see whats wrong with the `TCON` frame (Content Type - The genre of a song)\n\n![Hex dump of a comment frame](screenshots/04.jpg?raw=true)\n\nAs already seen by the `--get-frames` output, there are two BOMs in the frame. The first byte 0x01 defines the encoding of the frame as _UTF-16_.\nThe [ID3v2 standard then expects a single byte order mark (BOM)](http://id3.org/id3v2.3.0#ID3v2_frame_overview).\nThe first one tells us, that a _UTF-16 LE_ (Little Endian) encoded string follows.\nThen a new BOM appears defining an different flavor (_UTF-16 BE_ - Big Endian).\nThe text string itself is actually _UTF-16 BE_.\nThe second BOM violated the ID3v2 standard so that the bytes gets interpreted as an _UTF-16 LE_ encoded string.\n\nFurthermore the 'ä' got replaced by a 'd' which indicated further Unicode problems in the deeper inside of the tool I used to tag the file initially.\n\n\n## Installation\n\n 1. Install dependencies:\n    * `git`\n    * `clang`\n    * `zlib` (On Linux)\n    * [libprinthex](https://github.com/rstemmer/libprinthex)\n 2. You should check the `install.sh` script before executing. The default installation path is _/usr/local/bin_.\n 3. Follow the following instructions:\n\n```bash\n# On Linux: Install clang and zlib\npacman -S git clang zlib # Use the package manager of your distribution\n# On MacOS:\nxcode-select --install # In case git/clang do not work yet\n\n# Install libprinthex\ngit clone https://github.com/rstemmer/libprinthex.git\ncd libprinthex\n./build.sh\nsudo ./install.sh # Installs to /usr/local/{lib,include}\n\n\n# download\ngit clone https://github.com/rstemmer/id3edit.git\ncd id3edit\n\n# build\n./build.sh\n\n# install\nsudo ./install.sh\n```\n\n## Usage\n\n * `id3edit --help` to see all available options.\n * `id3edit --version` to get the version number only, easy to parse without any escape sequences ;)\n\nShortcuts:\n \n * `id3show $FILE`: `id3edit --readonly --get-all $FILE`\n * `id3frames $FILE`: `id3edit --readonly --get-frames $FILE`\n * `id3dump $FRAMEID $FILE`: `id3edit --readonly --dump $FRAMEID $FILE`\n\n## Contribute\n\nIn case you find a bug feel free to create an Issue.\n\nIf you have a mp3 file with invalid meta data and you cannot debug it with `id3edit`, create an Issue and append the invalid file to it (or at least the ID3 Tag).\n\nPull requests are welcome as well.\n\nBare mp3 files start with the magic number `0xFF, 0xFB`.\nSometimes the second byte is different, because this magic number is not really magic, it already contains information about the encoding.\nIn case you find a valid mp3 file and get the error `\"ID: '???' (??????) not supported!` create an Issue and post the following output:\n\n```bash\nid3edit --readonly --showheader invalid.mp3\nhexdump -C invalid.mp3 | head \n```\n\nIn general posing the following information can be helpful to find a bug:\n\n```bash\nid3edit --readonly --showheader --get-all --get-frames bugtrigger.mp3\nhexdump -C bugtrigger.mp3 | head -n 50\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstemmer%2Fid3edit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstemmer%2Fid3edit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstemmer%2Fid3edit/lists"}