ZoryaTag 1.0.1 · user manual

Tag, rename and package sync deliveries from one catalog

ZoryaTag turns one catalog of tracks and versions into a delivery ZIP: renamed copies of your WAV and MP3 files with your metadata embedded, the matching spreadsheet (CSV) and a receipt. Your original files are only read, never changed. Everything runs inside one HTML page on your computer.

1. Before you start

A desktop computer with a current Chromium-based browser (Google Chrome or Microsoft Edge). Tested: Google Chrome 152.0.7977.82 (automated headless runs) on Ubuntu Linux 22.04 (x86-64), desktop 1280×800 and narrow 375 px layouts. Other browsers were not tested.
Unzip ZoryaTag-1.0.1.zip to a folder you control. No installation, account or internet connection is needed.
Open ZoryaTag.html by double-clicking it (or drag it into a browser window).

2. First result in five minutes (the bundled example)

ZoryaTag start screen with Load example catalog, Start an empty catalog, Import catalog CSV and Open project buttons — The start screen. Every action is a button and can be reached with the Tab key.

Click Load example catalog. The fictional artist “Lumen Harbor” appears with 3 tracks × 3 versions (6 WAV, 3 MP3). ZoryaTag opens the Check step.
One problem is listed on purpose: “Glass Tide: writer shares total 90%, not 100%.” Click Show.
Check step: blocking problems on the left, the exact output names on the right.
The catalog opens with the writer table focused. Change M. Reyes’s share from 40 to 50. The total turns green: “Total 100% ✓”.
Catalog step: track details, writers and publishers, versions with ISRCs and attached audio. The right panel shows each file’s format and which old tags will not be copied.
Click Check delivery. The banner says “No blocking problems”.
Ready to export. The template defines file names and spreadsheet columns.
Click Continue to export, read and tick the acknowledgement, then click Build ZIP. Your browser saves Generic-Library.zip.
Result: 9 tagged copies, audio payloads unchanged, and the old tags that were not copied.

Expected result. The ZIP contains Generic-Library/audio/ with 9 files, Generic-Library-metadata.csv with 9 rows, receipt.html and receipt.json. For example Lumen Harbor - Glass Tide - Instrumental.wav carries title “Glass Tide (Instrumental)”, ISRC QZXX12600002 and writer splits “A. Lind (ASCAP, 00000000012) 50%; M. Reyes (BMI, 00000000034) 50%”, and its audio data is byte-for-byte the same as glass_tide_inst_v3.wav. Compare your spreadsheet with examples/expected/Generic-Library-metadata.csv.

3. Your own catalog and audio

Start an empty catalog, or Import catalog CSV (one row per version; use the column names from examples/lumen-harbor-catalog.csv or from Export catalog CSV). Rows with the same Track ID (or the same title and artist) become one track; its first row supplies the shared details and ZoryaTag tells you about rows that disagree.
Fill in the track details once. Every version (Main, Instrumental, 30s, stems…) inherits them; each version has its own label, ISRC and audio file.
Click Add audio files and select your WAV/MP3 files. A version is attached automatically only when its Source filename equals a loaded file name exactly and only one loaded file has that name. Otherwise pick the file from the version’s list; each loaded file has a number (#1, #2…), size and modified date so files with the same name can be told apart. The receipt records whether each file was matched by name or chosen by you.
After each selection the panel states how many files were added, how many are ready and how many were rejected (each rejected file shows its reason). The list holds at most 100 files, rejected ones included. If a selection does not fit, nothing from it is added and the panel says how many more files fit; select fewer files or use Remove from list first.

Audio panel showing two rejected files with reasons, RF64 not supported and not a RIFF WAVE file, and the message: Added 2 files to the list: 0 ready, 2 rejected — Files that cannot be handled safely are refused with a reason and are never attached. The message counts the ready and rejected files of each selection.

ZoryaTag catalog on a 375 pixel wide screen — Narrow window (375 px). Wide tables scroll inside their box.

4. Supported files and limits

Input	Supported	Refused with a message
WAV	RIFF/WAVE, PCM 8/16/24/32-bit, IEEE float 32/64-bit, WAVE_FORMAT_EXTENSIBLE with PCM/float; 1–8 channels	RF64/BW64, RIFX, compressed WAV, truncated or overrunning chunks, extra bytes after the RIFF end, two fmt/data chunks, data before fmt, partial sample frames
MP3	MPEG-1/2/2.5 Layer III; an existing leading ID3v2.2/2.3/2.4 tag; trailing APEv2 and ID3v1 tags	Free-format or damaged frames, a truncated final frame, several leading ID3v2 tags, Lyrics3, Enhanced TAG+, appended ID3v2 footers, files without a valid frame sequence in the first 64 KiB
Catalog CSV	UTF-8 (BOM allowed), comma or semicolon	Over 2 MiB, 2,000 rows, 80 columns or 4,000 characters per cell
Delivery	Up to 100 audio files in the list, 128 MiB per file and 512 MiB in total; the ZIP must stay under 1 GiB. A selection that would take the list past 100 files is refused as a whole, before any file is read. AIFF, FLAC, M4A and OGG are not supported.

5. What the checks mean

Required fields come from the selected template.
Shares: writers and publishers must each total exactly 100% (two decimals, e.g. 33.33 + 33.33 + 33.34). This is arithmetic on what you typed, not proof of ownership. Not legal advice.
ISRC must have the 12-character shape (hyphens are removed); IPI should have 9–11 digits. These are shape checks, not registry lookups.
Emoji and other characters outside the Basic Multilingual Plane cannot be stored in ID3v2.3 tags; export is blocked until you remove them. Cyrillic, accented Latin and other common scripts are fine.
Output names are converted to safe ASCII names (Cyrillic is transliterated). Names that would collide get _2, _3; the preview shows them before export and the same names are used in the audio folder, CSV and receipt.

6. What is written into the copies

MP3: a new ID3v2.3 tag followed by the original audio frames unchanged. Old ID3v2, APEv2 and ID3v1 tags are removed so stale titles cannot contradict the new ones (the receipt lists what was removed).

WAV: all original chunks in their original order and unchanged (including data, bext, iXML, cue points and unknown chunks), except old RIFF INFO and ID3 chunks; then a new RIFF INFO list (title, artist, comment, copyright, genre, year, keywords, software; UTF-8) and a new id3 chunk with ID3v2.3.

ID3v2.3 fields: TIT2 title (with the version in brackets for non-Main versions), TPE1 artist, TCOM writers, TPUB publishers, TBPM, TKEY (when the key can be written as e.g. F#m), TCON genre, TSRC ISRC, TYER year, TCOP copyright, COMM description, and TXXX fields VERSION, MOODS, KEYWORDS, WRITER_SPLITS, PUBLISHER_SPLITS, CONTACT, CATALOG_NUMBER.

Existing tags, artwork and fields outside this list are not carried into the copies. You must acknowledge this before each export.

7. Reviewing the ZIP

Open receipt.html in your browser: each output file, its source, how it was attached, the audio-payload SHA-256 (identical before and after), old tags not copied and every field written.
Open the CSV in your spreadsheet application. Cells that begin with = + - @ are prefixed with an apostrophe so spreadsheets do not run them as formulas.
Check a few copies in your usual tagger or player. Players differ: many ignore WAV tags entirely, which is why the spreadsheet is always included.

8. Saving and reopening

Save project downloads catalog.zoryatag.json, which reopens exactly (all fields, writers, publishers, versions and custom templates). Nothing is shortened on reopening: a value ZoryaTag cannot export, such as a field over 4,000 characters, is kept and listed on the Check step. Browsers cannot keep access to your audio files, so after Open project add the audio files again; versions re-attach by exact filename. Export catalog CSV is for spreadsheets; the project file is the lossless format.

9. Editing templates

Choose Download this template, edit the JSON in a text editor and use Import template JSON. Keys: name, folder, filename (tokens {artist} {title} {version} {bpm} {key} {catno} {isrc} {n}), title_version_suffix, required and columns (each with header and a field such as title_full, isrc, writer1_name, writer_splits, duration). The bundled templates are generic examples, not any library’s official requirements; follow the instructions of the library you deliver to. A project keeps up to 20 imported templates.

10. Troubleshooting

Symptom	What to do
“Nothing was added. You selected … files”	The audio list holds at most 100 files, rejected ones included. Select no more than the number of files the message says still fit, or use Remove from list on files you do not need, then add again.
“no audio file attached”	Make the version’s Source filename match the file name exactly (including extension) or choose the file in the version’s list.
“RF64/BW64 … not supported”	Export a standard WAV under 2 GiB (most DAWs offer “WAV” vs “RF64/BWF large file”).
“not a RIFF/WAVE file”	The file is probably AIFF or FLAC renamed to .wav. Convert it to WAV first.
MP3 “Lyrics3”, “TAG+” or “several leading ID3v2 tags”	Remove those tags with your usual tagger, save, and add the file again.
Player does not show WAV tags	Many players ignore WAV metadata. Send the spreadsheet; check tags with a tagger that reads WAV ID3 chunks.
Non-ASCII text looks wrong in an old WAV reader	RIFF INFO is written as UTF-8; some older readers assume a Windows code page. The ID3 chunk and CSV carry the same text.
Build ZIP stays disabled	Fix every item on the Check step and tick the acknowledgement.
Export stopped with “No ZIP was created”	The message names the file. Nothing partial was saved; fix or remove that file and build again. Cancel stops after the current file the same way.

11. Privacy and uninstall

ZoryaTag makes no network requests (the page’s security policy blocks them) and never uploads anything. Files are read by your browser only when you choose them. To uninstall, delete the unzipped folder and any ZIPs or project files you saved.

Example music, names, ISRCs (QZXX126…) and IPI numbers are fictional and first-party. ZoryaTag is not affiliated with any library, PRO or tagging application.