Step 2: Fill In Your Track Data #
Here is the version of the CSV help guide that can be found by pressing the button above that says “Download CSV Help Guide”
| Note: CSV import does not support writers, musicians, publishing deals, or file attachments. These must be added manually or via bulk edit after import. |
If you’ve never worked with a CSV import before, here’s the short version of what you’re doing: you’re filling out a spreadsheet (saved as a .csv file) where each row is one track, and each column is one piece of information about that track — like its title, length, or who wrote it.
Every field below is shown in a table with three columns:
- Field Name — the exact column header you’ll use in your CSV (case-sensitive, so type it exactly as shown)
- Value(s) Expected — what kind of information goes in that column, and the exact words/formats it accepts
- Notes / Comments — anything that will help you avoid mistakes, including what happens if you get it wrong
Each field is also labeled REQUIRED, sometimes required, or Optional so you know at a glance what you can skip.
| QUICK TIP If you are looking to import a high quantity of tracks, try testing with a handful to make sure you have an understanding of the format that is needed! |
| Quick Definitions Semicolon-delimited list = multiple items in one cell, separated by semicolons. Example: Uplifting; Hopeful; Driving Free text = you can type anything you want here; there’s no fixed list of allowed values. Case-insensitive = capitalization doesn’t matter (“song” and “Song” both work). |
The CSV Header Row #
Before listing each field individually, here is the complete header row exactly as it should appear as the first line of your CSV file. Copy this exactly — the order of these columns does not actually matter for import, but starting from this row guarantees you haven’t misspelled or missed a column name.
title,isRegistered,isSigned,trackLength,trackType,keyOfTrack,trackBPM,status,artist,description,genre,subGenres,moods,instruments,tvShowsSimilarTo,bandsSimilarTo,keywords,lyrics,comments,album,isrc,iswc,proRegistrationNumber,proRegistrationDate,copyrightYear,writers,musicians,publishingDeals
Notice that writers, musicians, and publishingDeals are included at the end — these three columns are special. They each support multiple ways of formatting their data, and they get their own detailed sections later in this guide.
Core Track Fields #
These are the basic, single-value fields that describe a track. Most are optional — only title and trackType are truly required.
| Field Name | Value(s) Expected | Notes / Comments |
| title REQUIRED | 3–60 characters Free text | This is the only field that will always block import if missing. Must be at least 3 characters and no more than 60. |
| trackType REQUIRED | Song Instrumental Work for Hire | Spelling/capitalization doesn’t matter (matching is case-insensitive), but the value must be one of these three options — anything else will cause the row to be rejected. |
| isRegistered Optional | Y N Yes No | If you type something that isn’t recognized, it will silently default to N — so double-check spelling if this matters to you. |
| isSigned Optional | Y N Yes No | Same behavior as isRegistered above: gets normalized to Y/N, and unrecognized values quietly become N. |
| trackLength Optional | mm:ss hh:mm:ss ss (just seconds) | You can type the length in whichever of these three formats is easiest — it’s automatically converted to seconds on import either way. |
| trackBPM Optional | Whole number (integer) | If you enter 0, leave it blank, or type something that isn’t a valid number, it’s treated as empty rather than causing an error. |
| keyOfTrack Optional | Free text | Example values: C Major, A Minor. There’s no fixed list — type the key however you’d naturally write it. |
| description Optional | Free text | If your description contains a comma or a line break, that cell must be wrapped in quotation marks in the CSV file (standard CSV quoting — most spreadsheet programs do this automatically when you save as .csv). |
| lyrics Optional | Free text, multi-line allowed | Same quoting rule as description: if the lyrics span multiple lines or include commas, the cell needs to be properly quoted. |
| comments Optional | Free text | General track-level notes — not tied to any specific writer or musician. |
| album Optional | Free text | The name of the album this track belongs to, if any. |
| isrc Optional | Free text | The track’s ISRC (International Standard Recording Code), if it has one. |
| iswc Optional | Free text | The track’s ISWC (International Standard Musical Work Code), if it has one. |
| proRegistrationNumber Optional | Free text | The registration ID from your Performing Rights Organization (e.g., ASCAP, BMI), if applicable. |
| proRegistrationDate Optional | YYYY-MM-DD M/D/YYYY MM/DD/YYYY M-D-YYYY MM-DD-YYYY 2-digit-year versions of the above | Several date formats are accepted, so use whichever is most natural for you — just be consistent within your own file to avoid confusing yourself later. An invalid/unrecognized date format will cause that row to be rejected. |
| copyrightYear Optional | 4-digit year | Must fall between 1900 and one year in the future from today. Anything outside that range will cause the row to be rejected. |
Classification and Catalog Fields #
These fields help organize and categorize your tracks — genre, mood, instrumentation, and similar-sounding references. Several of these accept multiple values in a single cell using a semicolon (;) to separate each item.
| Field Name | Value(s) Expected | Notes / Comments |
| genre Sometimes required | Free text | Not strictly required, but if you do provide a value, it should be at least 3 characters long. If the genre is not found, it will add it to your database. |
| subGenres Optional | Semicolon-delimited list | Example: Acoustic Pop; Indie Pop Note: this column can also be written as lowercase subgenres — both spellings are accepted. If the subgenre is not found, it will add it to your database. |
| moods Optional | Semicolon-delimited list | Example: Uplifting; Hopeful; Driving Spaces around each item are ignored, so “Uplifting; Hopeful” and “Uplifting;Hopeful” both work the same. If the mood is not found, it will add it to your database. |
| instruments Optional | Semicolon-delimited list | Example: Acoustic Guitar; Piano. If the instrument is not found, it will add it to your database. |
| status Optional | Free text | If you type a status that doesn’t already exist in your catalog, a new one is automatically created for you — there’s no fixed list to match against. |
| artist Optional | Free text | Same behavior as status: a new artist entry is created automatically if it doesn’t already exist. |
| keywords Optional | Semicolon-delimited list | Example: sunrise; hopeful; cinematic |
| tvShowsSimilarTo Optional | Semicolon-delimited list | Example: Suits; Euphoria Used to describe the vibe/placement style your track would suit. |
| bandsSimilarTo Optional | Semicolon-delimited list | Example: Coldplay; Keane |
| Remember: Semicolons, Not Commas, for Lists For subGenres, moods, instruments, keywords, tvShowsSimilarTo, and bandsSimilarTo — always separate multiple items with a semicolon ( ; ), never a comma. This matters because commas are already used elsewhere in CSV files to separate columns — using a comma inside a list would confuse the import. Spaces around each item are ignored, so feel free to format it however is easiest to read. |
The Writers Column #
This is one of the three “advanced” columns, along with musicians and publishingDeals. Unlike the simple fields above, writers can be entered in five different formats. You only need to use one — pick whichever feels easiest.
Why Five Formats? #
Composer Catalog supports multiple formats so that the same column works whether you’re typing values in by hand, copying from an export, or generating the file programmatically. For manual editing, format #2 (the readable, labeled format) is recommended.
Format 1 — Names Only #
The simplest option. Just list the names, separated by semicolons if there’s more than one.
John Doe; Jane Smith
Use this when you don’t need to record contribution type, percentage, or comments — just who the writers are.
Format 2 — Readable Labeled Format (Recommended) #
This is the format recommended for manual editing. The pattern looks like this:
FirstName LastName (Contribution: value, Percentage: value%, Comments: “text”)
Here’s a real example with two writers:
John Doe (Contribution: music-only, Percentage: 50%); Jane Smith (Contribution: lyrics-only, Percentage: 50%)
Format 3 — Legacy Positional Format #
An older, shorter format that doesn’t use labels — just the values in a fixed order, inside parentheses:
John Doe (music-only, 50%)
Format 4 — Full Key:Value Format #
A more verbose alternative to Format 2, written as a comma-separated list of labeled fields:
Name: John Doe, Contribution: music-only, Percentage: 50%
Format 5 — JSON Re-Importable Format #
This format is generated automatically when you export your catalog with the re-importable option turned on (see the JSON section later in this guide). It’s not something you’d typically type by hand, but it’s the most reliable way to move data between catalogs without losing detail.
{“schema_version”:1,”writers”:[{“firstName”:”John”,”lastName”:”Doe”,”contributionType”:”music-only”,”contributionPercentage”:50,”trackComments”:”Main melody”}]}
Writer Fields Explained #
| Field Name | Value(s) Expected | Notes / Comments |
| Contribution Optional | lyrics-only music-only music-and-lyrics | These three are the official values, but the system is flexible — it also accepts common everyday variants like Lyrics, Music, or Music & Lyrics and converts them automatically. |
| Percentage Optional | A number (the % sign is optional) | You can type 50 or 50% — both work the same. |
| Comments Optional | Free text | If your comment contains a comma, wrap it in quotation marks (as shown in the examples above) so it isn’t mistaken for a field separator. |
The Musicians Column #
The musicians column works almost identically to writers, but tracks different information — instead of “Contribution” and songwriting credit, it tracks each musician’s Duty (what they played/performed) and their Work For Hire Status.
Format 1 — Names Only #
Jane Smith; Bob Johnson
Format 2 — Readable Labeled Format (Recommended) #
Pattern:
FirstName LastName (Duty: value, Work For Hire Status: value, Comments: “text”)
Example with two musicians:
Jane Smith (Duty: Drums, Work For Hire Status: sent); Bob Johnson (Duty: Guitar, Work For Hire Status: not-required)
Format 3 — Legacy Positional Format #
Jane Smith (Drums, Sent)
Format 4 — Full Key:Value Format #
Name: Jane Smith, Duty: Drums, Work For Hire Status: Sent
Format 5 — JSON Re-Importable Format #
{“schema_version”:1,”musicians”:[{“firstName”:”Emily”,”lastName”:”Anderson”,”duty”:”Lead Vocals”,”workForHireStatus”:”signed-and-completed”,”trackComments”:”Primary vocal”}]}
Musician Fields Explained #
| Field Name | Value(s) Expected | Notes / Comments |
| Duty Optional | Free text | What the musician did on the track — e.g., Drums, Lead Vocals, Guitar. There’s no fixed list; type it however makes sense. |
| Work For Hire Status Optional | not-required not-sent sent signed-and-completed | These four are the official values, but matching is flexible about capitalization, spacing, and hyphens, so close variants will still be recognized. |
| Comments Optional | Free text | Wrap in quotation marks if the comment contains a comma. |
The Publishing Deals Column #
This is the most complex of the three advanced columns, because a single track can have multiple publishing deals, and each deal can involve multiple publishers. To make that possible in one cell, four different separator characters are used, each with its own job. This is the one section worth reading slowly.
The Four Separator Characters #
| Separator Character | Value(s) Expected | Notes / Comments |
| || (double pipe) | Separates multiple deals | Use this when a single track has more than one publishing deal entirely. |
| ; (semicolon) | Separates top-level fields within one deal | Used to separate things like the publisher info from “Signed As” from “Comments” within a single deal. |
| | (single pipe) | Separates multiple publishers within one deal | Used only when one deal has more than one publisher attached to it (a co-publishing split). |
| , (comma) | Separates fields within one publisher segment | Used to attach a percentage to a specific publisher’s name, for example. |
| Memory Trick Think of it as going from biggest to smallest: || splits deals, ; splits fields inside a deal, | splits publishers inside a field, and , splits details inside one publisher. Most of the time, if you only have one publisher and one deal, you’ll only ever need the semicolon ( ; ). |
Required and Optional Fields Per Deal #
| Field Name | Value(s) Expected | Notes / Comments |
| Publisher REQUIRED | Publisher: [name] | At least one publisher is required for every deal. If you have more than one publisher for the same deal, separate them with a single pipe ( | ). |
| Signed As REQUIRED | Exclusive Non-Exclusive Work for Hire | Note: “Unsigned” is NOT a valid value here — this field only applies to deals that have actually been signed. |
| Comments Optional | Free text | General notes about the deal. |
| Alternate Track Title Optional | Free text | Use this if the track is registered under a different title with this particular publisher. |
| Reversion Date Optional | YYYY-MM-DD | The date rights revert back to you, if applicable. Only this one date format is accepted here (unlike proRegistrationDate above, which accepts several formats). |
Worked Examples #
Example 1: One publisher, no extra details #
Publisher: Sunrise Music Publishing; Signed As: Exclusive
This is the simplest possible deal — just a publisher name and the signing type, separated by a semicolon.
Example 2: One publisher with a percentage and comments #
Publisher: Sony Music, Percentage: 50; Signed As: Work For Hire; Comments: Admin deal
Notice the comma between “Sony Music” and “Percentage: 50” — that comma attaches the percentage to that specific publisher. The semicolons still separate the bigger fields (Publisher info, Signed As, Comments).
Example 3: Multiple publishers in one deal (a co-publishing split) #
Publisher: Reely Note, Percentage: 75 | Publisher: 10 West, Percentage: 25; Signed As: Work For Hire
Here, the single pipe ( | ) separates the two publishers from each other, while each publisher’s own name and percentage are joined with a comma.
Example 4: Multiple deals on the same track #
Publisher: Sony Music; Signed As: Exclusive || Publisher: Warner Chappell; Signed As: Non-Exclusive
The double pipe ( || ) is what separates these into two completely separate deals.
How Percentages Are Calculated #
You don’t always have to do the percentage math yourself — the system will fill in gaps automatically under certain conditions:
- If there’s only one publisher and you don’t specify a percentage, it automatically defaults to 100%.
- If there are multiple publishers and any one of them is missing a percentage, OR if the percentages you entered don’t add up to exactly 100, the system throws out whatever percentages you typed and replaces them all with equal shares instead (rounded to two decimal places).
Practical takeaway: if you want specific, uneven percentage splits to actually take effect (like 75/25 rather than an automatic 50/50), make sure every publisher has a percentage listed and that they add up to exactly 100.
JSON Re-Importable Format (Advanced) #
This section is good to know about, but you generally won’t need to type this format by hand — it’s generated automatically when exporting your catalog.
When you export your catalog using the option collaborationsFormat=reimportable, the writers, musicians, and publishingDeals columns are written out as JSON objects instead of the readable formats shown above. Every JSON payload includes a schema_version: 1 marker, identifying the structure version so future updates stay backward-compatible.
Use this format specifically when you need full relationship metadata preserved — for example, contact-level details tied to a specific writer or musician — for a high-fidelity round trip (exporting and re-importing without losing any detail).
| When Should You Use JSON Instead of Readable Format? Use the readable format (described in the sections above) when you’re typing or editing values by hand. Use the JSON format only if you’re exporting from Composer Catalog itself and re-importing later, or if you’re working with the data programmatically (e.g., writing a script). |
CSV Quoting and Special Characters #
A few general rules apply across every field in this guide, not just the advanced columns:
- Standard CSV quoting rules apply throughout. If a field’s content contains a comma, a line break, or a quotation mark, that entire cell needs to be wrapped in quotation marks.
- Files exported from Composer Catalog already have every column quoted automatically, to maximize compatibility with different spreadsheet programs.
- Special punctuation (like curly quotes or em-dashes) is automatically normalized on export, so it displays correctly even in stricter CSV viewers.
Practical tip: most spreadsheet programs (Excel, Google Sheets, Numbers) handle this quoting automatically when you save/export as a .csv file — you typically don’t need to manually add quotation marks yourself unless you’re editing the raw text file directly.
What Happens If a Row Has a Mistake? #
Composer Catalog won’t reject your whole file just because one row has a problem. Instead:
- Invalid rows are skipped during import — they simply don’t get imported.
- You’ll see a report (the import summary) listing exactly which rows were skipped and why, after the import finishes.
The most common reasons a row gets skipped are:
- Missing or too-short title (must be at least 3 characters)
- Invalid trackType (must be exactly Song, Instrumental, or Work for Hire)
- Invalid proRegistrationDate (must match one of the accepted date formats)
- Invalid copyrightYear (must be a 4-digit year between 1900 and next year)
- Invalid structure in the writers, musicians, or publishingDeals columns (usually a missing required field, like a deal with no Publisher)
| Best Practice Before a Big Import Start with a small test batch — just 2 or 3 rows — to confirm your formatting is correct before importing your entire catalog at once. Check the import summary carefully after every import, even if it seems to have gone smoothly, since skipped rows won’t generate a hard error. |
Quick Copy/Paste Examples #
Each example below is a complete, ready-to-use value for a single CSV cell. Copy whichever matches your situation and adjust the names/details.
Writers (Readable Format) #
Single writer:
John Doe (Contribution: music-only, Percentage: 100%)
Two writers:
John Doe (Contribution: music-only, Percentage: 50%); Jane Smith (Contribution: lyrics-only, Percentage: 50%, Comments: “Topline v2”)
Musicians (Readable Format) #
Single musician:
Emily Anderson (Duty: Lead Vocals, Work For Hire Status: sent)
Two musicians:
Emily Anderson (Duty: Lead Vocals, Work For Hire Status: signed-and-completed); Mike Brown (Duty: Drums, Work For Hire Status: not-required, Comments: “Remote session”)
Publishing Deals (Readable Format) #
Single deal, one publisher:
Publisher: Sunrise Music Publishing; Signed As: Exclusive
Single deal, multiple publishers:
Publisher: Sunrise Music Publishing, Percentage: 60 | Publisher: Night Owl Songs, Percentage: 40; Signed As: Non-Exclusive; Comments: Co-pub split
Multiple deals in one cell:
Publisher: Sunrise Music Publishing; Signed As: Exclusive || Publisher: Night Owl Songs; Signed As: Work For Hire; Reversion Date: 2028-12-31
Writers (JSON Re-Importable Format) #
{“schema_version”:1,”writers”:[{“firstName”:”John”,”lastName”:”Doe”,”contributionType”:”music-only”,”contributionPercentage”:50,”trackComments”:”Main melody”},{“firstName”:”Jane”,”lastName”:”Smith”,”contributionType”:”lyrics-only”,”contributionPercentage”:50,”trackComments”:”Topline”}]}
Musicians (JSON Re-Importable Format) #
{“schema_version”:1,”musicians”:[{“firstName”:”Emily”,”lastName”:”Anderson”,”duty”:”Lead Vocals”,”workForHireStatus”:”signed-and-completed”,”trackComments”:”Primary vocal”},{“firstName”:”Mike”,”lastName”:”Brown”,”duty”:”Drums”,”workForHireStatus”:”not-required”,”trackComments”:”Live room take”}]}
Publishing Deals (JSON Re-Importable Format) #
{“schema_version”:1,”deals”:[{“signedAs”:”exclusive”,”publishers”:[{“name”:”Sunrise Music Publishing”,”percentage”:60},{“name”:”Night Owl Songs”,”percentage”:40}],”alternateTrackTitle”:”Morning Light Alt”,”reversionDate”:”2028-12-31″,”comments”:”Co-pub split”}]}
End of Guide. For the master list of every column name in the correct header-row order, see “The CSV Header Row” near the beginning of this document.
