catalog-value-estimator

What this skill does

# Catalog Value Estimator

Turn public streaming data into a defensible, reproducible estimate of a music
asset's **performance** and **value** — assembled with zero seller cooperation,
so it can be produced before a deal, used to verify a counterparty's claims, or
frozen as a baseline to measure impact over time.

The whole method rests on one identity:

> **Catalog value = sustainable annual Net Label Share (NLS) × a market multiple**

NLS is what the owner *keeps* after distribution and artist/producer royalties —
not gross streaming revenue. The job of this skill is to measure real streams,
convert them to annual NLS through a labeled, auditable assumption stack, apply
a multiple, and surface the risks (concentration, rights flags) that move the
multiple — all while being honest about what is *measured* vs *assumed*.

## When to use this

Reach for this skill for any of: valuing a catalog/album/track, projecting
annual NLS, building a portfolio baseline, tracking an asset's performance over
time, or producing a streams→revenue→value report. It works on one recording or
thousands. It does **not** need royalty statements — when those exist, use them
to calibrate (see "Verification loop").

## Prerequisites

- **Recoup API access.** All streaming data comes from the Recoup Research API
  (Songstats-backed). Set `RECOUP_API_KEY` (sent as `x-api-key`) **or**
  `RECOUP_ACCESS_TOKEN` (sent as `Authorization: Bearer`). In a Recoup sandbox
  `RECOUP_ACCESS_TOKEN` is already present. To get a key, see
  `references/recoup-api.md`.
- `python3` with `matplotlib` and `reportlab` (only for the PDF report):
  `pip install --break-system-packages matplotlib reportlab`.
- `curl` available on PATH (the scripts shell out to it).

## The loop (five steps)

1. **Assemble the asset + identifiers.** Resolve the recordings you want to
   value into Spotify track IDs or ISRCs, and confirm ownership from public
   metadata (the `℗`/P-line, `labels`, and `distributors` returned by the API).
   - Have ISRCs or Spotify track IDs already → skip to step 2.
   - Have a Spotify album → `scripts/fetch_album_tracks.py --album <id|url>`
     prints the track IDs.
   - Have only an artist/label name → resolve the catalog first (see
     `references/recoup-api.md`: `lookup`, `tracks`),
     then feed the IDs in.
2. **Measure streams.** For every track, pull all-time per-platform counts
   (`/research/track/stats`) and the trailing-12-month delta
   (`/research/track/historic-stats`, diff the cumulative `streams_total` at the
   window endpoints). `scripts/estimate.py` does both.
3. **Model gross → NLS → value.** Apply public per-stream rates, the deduction
   stack, and the multiple band from `references/methodology.md`. Keep
   *measured* platforms separate from *approximated* ones and carry a band, not
   a point.
4. **Surface risk.** Compute concentration (top-track and top-3 share of
   streams) and flag anything that moves the multiple — single-track
   dependency, plateauing run-rate, sample-driven hits, registration gaps.
   These are as important as the dollar figure.
5. **Report.** Emit the structured results, and — if the user wants something
   shareable — a branded executive PDF via `scripts/build_report.py`.

Run steps 2–4 with one command:

```bash
python3 scripts/estimate.py \
  --ids <comma-separated Spotify track IDs>   # or --isrcs / --ids-file
  --asset-name "K.I.D.S." --owner "Rostrum Records" \
  --out ./out
# -> out/estimate.json (full results) + out/summary.md (human-readable)
```

Then, optionally:

```bash
python3 scripts/build_report.py --estimate ./out/estimate.json --out ./out
# -> out/<asset>-baseline-report.pdf  (charts + valuation + methodology)
```

`estimate.py` and `build_report.py` are the workhorses — don't re-derive their
logic inline; call them so every run is identical and auditable.

## Reading the output

`estimate.json` contains, per asset: all-time and trailing-12-month streams per
platform, gross/NLS/value with low–central–high bands, the per-track table, the
concentration metrics, and the exact assumption set used (so any number can be
traced back). `summary.md` is the same thing in prose + a table.

Lead with what's **measured** (streams are real, pulled live) and present the
dollar figures as a **directional model** with assumptions visible. This matters
especially when sharing with a rights owner who knows their real numbers —
overclaiming a value you derived from public rates costs credibility.

## Honest limits (state these in any output)

- **Measured vs approximated platforms.** Songstats exposes per-track streams
  for Spotify, YouTube, and SoundCloud; Apple/Amazon/Deezer/Tidal return
  playlist data but not stream counts, so their revenue is a labeled gross-up.
  The measured-platform figure is a floor; true revenue is higher.
- **Master-side only by default.** This values recordings (NLS). Publishing
  (NPS — mechanical + performance) is separate and additive; only model it if
  the owner controls the compositions.
- **History depth.** Day-level streaming history typically starts ~2021, so
  annual trajectories may be ~5 years even for older catalogs. The all-time
  cumulative still reflects the full life.
- **Every rate, deduction, and multiple is an assumption** (see methodology).
  The multiple is the single biggest swing — concentration and a flat run-rate
  argue for the low end.

## Calibration & the verification loop

When a public comp exists (a reported sale/ask), sanity-check the estimate
against it — but match scope (a single album vs a multi-album, multi-artist
portfolio). When a real royalty statement becomes available, solve for the
counterparty's true blended per-stream rate and deduction stack, replace the
defaults, and the band collapses. Each real statement makes the next
permissionless estimate more accurate — fold corrections back into the config.

## What to read next

- `references/methodology.md` — the full assumption set: per-stream rates, the
  gross→NLS deduction stack, multiple bands, the gross-up, the TTM annualization
  mechanic, calibration, and caveats. **Read this before quoting any number.**
- `references/recoup-api.md` — auth and the exact endpoints used (`track/stats`,
  `track/historic-stats`, `tracks`, `lookup`, `spotify/album`), with examples.