Applied AI-Powered Music Production Workflows

The Royalty Reconciliation Tool

Last reviewed

Intermediate

What you'll learn

~30 min
  • Build a CLI that ingests royalty CSVs from multiple distributors
  • Understand royalty calculation mechanics including revenue-per-stream ranges you set from your own statements
  • Match and reconcile payments across platforms
  • Generate a summary report with discrepancy flags

What you’re building

You got paid last quarter. DistroKid says one number. TuneCore says another. CD Baby’s report looks completely different. Spotify for Artists shows stream counts that don’t match what any distributor is reporting. You open three spreadsheets, squint at column headers that are all named differently, and try to figure out if the numbers add up.

They usually don’t. Independent artists can lose royalties to reporting errors, timing mismatches, and calculation mistakes. Not fraud — just the messy reality of music distribution. Different distributors report different metrics, use different column names, cover different time periods, and handle currency conversion differently. Nobody is trying to cheat you. The system is just complicated enough that mistakes slip through.

You’re going to build a tool that reads CSVs from multiple distributors, normalizes everything into a common format, cross-references the numbers, and flags anything that looks off. One command, one report, no more guessing.

💬This is real money

Use your own statements to estimate the value of a discrepancy. Reporting periods, territories, and platform mix can change the result, but a few percent missed each month adds up over a year and across a catalog of 20 tracks. This tool pays for itself the first time it catches a discrepancy.


Why royalties are confusing

Before you build the tool, it helps to understand why reconciliation is hard in the first place:

  • Different column names: Same data, different headers; check each export’s first row and map its count and revenue columns explicitly.
  • Different time periods: One distributor reports monthly. Another reports quarterly. Payment dates often lag the actual streams by months.
  • Per-stream revenue is an average you work out afterwards: Spotify states it pays by streamshare, not a per-stream rate, and says payments vary with how your music is streamed and with your distributor agreement.
  • Currency conversion: International streams get paid in local currency and converted. The exchange rate used varies by distributor and payment date.
  • Track name matching: Your distributor might list “JADED” while another lists “Jaded” or “JADED (Original Mix).” Same track, different strings.

Your tool handles all of this automatically.

ℹSoftware pattern: Data reconciliation engine

Ingest data from multiple sources with different schemas, normalize to a common format, cross-reference, and flag discrepancies. This pattern is used in accounting, banking, inventory management — anywhere multiple systems track the same underlying data.


Before you start

First, if your AI tool is still open, leave it: type /exit and press Enter (if you use Antigravity, press Ctrl+D with nothing typed instead), and wait until you see the $ or % prompt. Make a clean folder for this lesson inside ~/producer-workbench:

Terminal window
mkdir -p ~/producer-workbench/05-royalty-reconciliation-tool && cd ~/producer-workbench/05-royalty-reconciliation-tool

On Windows PowerShell, run mkdir -Force ~/producer-workbench/05-royalty-reconciliation-tool; cd ~/producer-workbench/05-royalty-reconciliation-tool, or open the folder in your desktop agent app. Then start your agent the way your track’s setup lesson showed.

Switch to plan mode

Once your agent is open, switch to Plan mode inside the session (Shift+Tab, /plan, or your desktop app’s mode picker). In plan mode it asks clarifying questions and shows you a plan before building.

The conversation

Each message below is an example. Say it in your own words.

Say what you want

Start with a short plain-English description of what you want to build:

I want to build a tool that ingests royalty CSVs from multiple distributors, normalizes track titles and columns, cross-checks streams and revenue, and generates an HTML discrepancy report. Ask me what you need first.

Answer its questions

Your agent will ask a few questions about distributor formats, discrepancy thresholds, and sample data. Answer each briefly:

If it asksYou might say
Which distributor CSV formats and output should it support?Auto-detect DistroKid, TuneCore, and CD Baby CSV headers, and generate a standalone dark-theme HTML discrepancy report.
How should track titles, platforms, and dates be normalized?Lowercase titles and strip suffixes like “(Original Mix)”, standardize platform names, clean currency values, and format dates as YYYY-MM.
What rules should trigger a discrepancy flag?Flag stream differences over 15%, tracks missing from a distributor, and revenue over 10% below an optional configured per-stream range.
How should per-stream revenue ranges be configured?Keep them unset unless supplied from my own statements, and ship one illustrative placeholder range (0.003-0.005) for sample testing.
Should we include a sample data generator to test the flags?Yes, add —generate-sample to write three distributor CSVs with an 18% stream mismatch, a missing track, and a 12% drop.

Read the plan

Before approving, check the plan for four domain essentials:

  1. Header auto-detection and title normalization prevent false mismatches. Each CSV’s header row selects the right parser (or prints unrecognized headers clearly), and track titles strip suffixes like "(Original Mix)" or "(Radio Edit)" before grouping by track_title + platform + period.
  2. Discrepancy thresholds distinguish noise from real flags. Small timing differences under 5% are ignored; stream differences above 15%, tracks missing from a source, and revenue more than 10% below the low end of a configured range are flagged as review items (not confirmed payment errors).
  3. The --generate-sample mode creates a self-contained test suite. Running node src/cli.js --generate-sample -o ./test-report writes sample-distrokid.csv, sample-tunecore.csv, and sample-cdbaby.csv with the three planted discrepancies ready to reconcile.
  4. The HTML report works offline as a standalone dark-theme file. All CSS is inline (#0a0a0a background, #f97316 accents), currency values round to two decimal places for display, and tables show summary totals, per-track comparisons, and flagged rows.

If the first plan hardcodes fixed per-stream rates as industry facts or leaves out --generate-sample, say so briefly:

Make per-stream ranges optional config values with one illustrative placeholder for sample data, and include the --generate-sample flag with three test CSVs.

When the plan covers all four, approve it: pick the option to proceed or say Yes, go ahead and build it (in Codex, press Shift+Tab first to leave plan mode). Once you verify the sample CSVs reconcile and flag all three discrepancies in report.html, ask your agent to save a Git checkpoint:

Save a checkpoint with Git so we can roll back if needed.
💡The sample data is your test suite

The --generate-sample flag creates CSVs with known discrepancies baked in. When you run the reconciler on sample data, you know exactly what flags should appear. If the tool catches all three planted discrepancies, it’s working correctly. This is a built-in sanity check.


What you get

After your AI CLI tool finishes, you’ll have a project folder structure like this:

royalty-tool/
package.json
src/
cli.js
parsers/
distrokid.js
tunecore.js
cdbaby.js
auto-detect.js
reconciler.js
reporter.js
sample-data.js
templates/
report.html

Run and test it with sample data

Ask your agent to install what is needed, generate the sample distributor CSVs, reconcile them, and open the HTML report:

Install what the tool needs, generate the sample distributor CSVs, reconcile them for Q4 2025, and open test-report/report.html in my browser.

If you prefer running the commands in a terminal yourself:

Terminal window
cd royalty-tool
npm install
node src/cli.js --generate-sample -o ./test-report
node src/cli.js -p "Q4 2025" -o ./test-report \
./test-report/sample-distrokid.csv \
./test-report/sample-tunecore.csv \
./test-report/sample-cdbaby.csv

When ./test-report/report.html opens in your browser, you should see:

  • Summary with total revenue broken down by Spotify, Apple Music, Amazon, YouTube Music, and Tidal
  • Per-track breakdown showing each track’s streams and revenue from each distributor
  • Discrepancy table with at least 3 flags (the ones planted in the sample data):
    • A stream count mismatch (~18% difference between distributors)
    • A missing track (present in DistroKid and TuneCore but absent from CD Baby)
    • A revenue flag (actual revenue 12% below expected based on the placeholder range)

If all three discrepancies show up in the report, your tool is working.

With your real data

  1. Export your royalty CSV from DistroKid; check its current help documentation for the export steps
  2. Export your royalty CSV from TuneCore; check its current help documentation for the export steps
  3. Run the tool with your real files:
Terminal window
node src/cli.js -p "Q4 2025" \
~/Downloads/distrokid-earnings.csv \
~/Downloads/tunecore-report.csv
ℹYou don't need all three distributors

Most artists use one or two distributors. The tool works with any combination — two DistroKid files from different periods, one DistroKid and one TuneCore, or all three. The reconciler compares whatever you give it.


A worked example: reconciling Q4

Here’s what a real reconciliation workflow looks like. Say you distributed through DistroKid and TuneCore last quarter. You download both CSVs and run:

Terminal window
node src/cli.js -p "Q4 2025" distrokid-q4.csv tunecore-q4.csv

The report shows:

TrackPlatformDistroKid StreamsTuneCore StreamsDifference
JADEDSpotify12,45012,380-0.6%
KICK IT W/USpotify8,2008,190-0.1%
MOODApple Music3,1002,540-18.1%
LIVE IT UPSpotify5,8005,790-0.2%

That 18% difference on MOOD’s Apple Music streams? That’s a flag. Could be a reporting delay, could be a territory exclusion, could be an actual error. Either way, you now know about it. You can check with your distributor instead of assuming everything is fine.

⚠This catches errors, not fraud

Distributors aren’t stealing from you. The music royalty system involves dozens of intermediaries, currency conversions, and reporting timelines. Mistakes happen at scale. This tool helps you spot them so you can follow up — not so you can accuse anyone of wrongdoing. A polite “I noticed a discrepancy in my Q4 Apple Music numbers, can you check?” gets results.


If something is off

ProblemFollow-up prompt
CSV parsing fails with encoding errorsThe CSV reader is choking on my DistroKid export, likely from hidden encoding characters at the start of the file. Strip any byte-order marks and handle non-UTF-8 exports cleanly before reading the rows.
Date formats don’t parse correctlyThe date parsing is failing on my TuneCore file. Check the date format in its first rows and handle YYYY-MM-DD, MM/DD/YYYY, "Mon DD, YYYY", and "DD Mon YYYY" formats, normalizing all dates to YYYY-MM.
Track names don’t match across distributors"JADED" from DistroKid isn't matching "Jaded (Original Mix)" from TuneCore. Lowercase both track titles, strip parenthetical suffixes like "(Original Mix)", "(Radio Edit)", "(Extended Mix)", and "(Remix)", and trim whitespace before comparing.
Currency conversion is wrongSome rows in my CD Baby export report revenue in EUR or GBP instead of USD. Detect the currency symbol or Currency column, convert to USD using configurable exchange rates, and flag any rows where currency conversion was applied.
Report shows zero revenue for some tracksThe revenue column is parsing as zero for tracks that definitely have earnings. Check the actual revenue column name in my file and add it, plus any variants I list, as recognized column names.

How per-stream revenue varies

The reconciler uses ranges you configure to flag suspicious revenue. Here’s why those numbers matter:

🔍What moves your per-stream averageclick to expand

Per-stream rates are not fixed, and Spotify does not publish one. Set your ranges from your own statements, not from a published rate. They vary by:

  • Platform: Compare each platform with your own historical statements.
  • Territory: Compare territories within your own statements; the revenue you average per stream can differ by country.
  • Listener type: Spotify pays out of both Premium subscription fees and ad revenue, so your mix of Premium and ad-supported listeners can move your average.
  • Total platform streams: Spotify pays by streamshare — your share of net revenue depends on your share of total streams. Spotify counts total streams each month, so a month with heavy streaming elsewhere can lower what your own share of streams earns.

The tool flags revenue that is more than 10% below the low end of each range you configure. A result outside your configured range warrants review; it does not establish a payment error.


Customize it

Add historical trend analysis

Add a --history flag taking a directory of past reports and render a visual Trends section in the HTML report flagging tracks down over 20%.

Add tax reporting summary

Add a --tax flag that outputs a tax-summary.csv grouped by territory with track_title, total_revenue_usd, platform, territory, quarter, and a totals row.

Build a projected earnings calculator

Add a Projections section to the HTML report estimating next quarter's earnings with 5% monthly catalog decay, 2x new-release boost, and confidence ranges.

Set up drop alerts

Add a --watch flag comparing against the previous history report and printing a terminal and HTML red banner alert if streams drop 30% or revenue drops 25%.

🔧

When Things Go Wrong

Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.

Symptom
The auto-detect picks the wrong parser for my CSV
Evidence
Running the tool on my DistroKid export says 'Detected format: tunecore' and the parsed data is all wrong
What to ask the AI
"The auto-detection is matching the wrong format. Make the header matching more specific: require at least 3 header matches (not just 1) before selecting a format. Use the real headers from my files as the required matches (the sample headers above are illustrative). Print which headers were matched so I can debug."
Symptom
The reconciler shows every track as a discrepancy
Evidence
The discrepancy table has 40+ rows and every single track is flagged, even ones where the numbers are close
What to ask the AI
"The discrepancy threshold is too sensitive. Only flag stream differences >15% AND revenue differences >10%. Small variations (under 5%) are normal due to reporting timing. Add a 'tolerance' zone: <5% = no flag, 5-15% = info, >15% = warning, >25% = alert."
Symptom
The HTML report is unstyled or looks broken
Evidence
Opening report.html shows raw text with no formatting, or the dark theme isn't applied
What to ask the AI
"Opening report.html shows unstyled raw text instead of the dark-theme report. Make sure the generated HTML embeds all dark-theme styling directly inside the file and writes the final values rather than raw template placeholders."
Symptom
Revenue numbers show way too many decimal places
Evidence
The report shows values like '$42.876543210987' instead of '$42.88'
What to ask the AI
"Revenue numbers in the report show long decimal strings like '$42.876543210987' instead of dollars and cents. Keep full precision during calculations, and round displayed dollar amounts to two decimal places in the report."
Symptom
The tool crashes on a CSV with empty rows or trailing commas
Evidence
Error: Cannot read property 'trim' of undefined on line 847 of reconciler.js
What to ask the AI
"The tool crashes on CSV exports from Excel that have blank rows at the end or trailing commas. Ignore empty rows and handle blank cells gracefully without crashing."

Try it yourself

  1. Open your AI tool in your lesson folder and switch to plan mode.
  2. Talk your agent through the plan and approve it to build the tool.
  3. Ask your agent to install what is needed, generate the sample data with --generate-sample, and run the reconciliation (or run the commands in your terminal).
  4. Open the HTML report and verify the three planted discrepancies show up.
  5. If you have real distributor CSVs, run those through and see what you find.

Key takeaways

  • Distributor CSVs are messy — different column names, date formats, and encoding. Auto-detection and normalization handle this so you don’t have to.
  • Your own statements are your benchmark — ranges you set from past statements give you a rough floor. Revenue below that floor means something is worth investigating.
  • Reporting issues are common — this isn’t paranoia, it’s the reality of a complex system with many intermediaries. The tool helps you catch what you’d otherwise miss.
  • Reconciliation is a pattern, not a one-time task — run this every quarter when you get paid. Keep the reports. Trends over time reveal more than any single snapshot.
  • This tool catches errors, not fraud — approach discrepancies as honest mistakes to be clarified, not accusations to be made.

KNOWLEDGE CHECK

Your reconciliation report shows that your track 'MOOD' earned $38 from 12,000 Spotify streams. Suppose your tool is configured with a placeholder range of $0.003-0.005 per stream (a fictional value for this exercise, not a Spotify figure). Should this be flagged?


What’s next

In the next lesson, you’ll build The Release Ops Command Center — a static site that pulls together everything from Lessons 1-5 into a single weekly action-plan dashboard. Campaign status, revenue numbers, royalty flags, and platform analytics, all in one place. Lessons 7 and 8 then move on to the audio visualizer and its content pipeline.

intellimetrics · Arlington, VA
© 2026 intellimetrics.net
Search lessons