Music Rights Management
Composition and master rights tracking, royalty splits, distribution
Collaborators
philcal (project owner)
How do I use this software?
This software runs wherever suits you — you just need somewhere to host it. Pick the option that fits your team:
| Option | What it means |
|---|---|
| Self-hosting | Set up the environment and run it yourself, on your own infrastructure. |
| Tooltwist hosting | Tooltwist can host and run it for you. |
| Other providers | Find a host in the provider directory — or, if you already have a support company, we're happy to give them the tools to deploy the application for you. |
Licensing
This variant is open source — you're free to use it and modify it at no cost. Hosting and support arrangements are provided separately and are not covered by this licence.
Who can help me?
Plenty of people can help you get the most from this software — browse the provider directory. Some providers can host it for you, others can customise it to your needs, and others again offer technical support and a helpdesk.
Tooltwist can host and customise the software for you, and Twist Teams provides technical support services.
Already have a support provider? We're happy to give them the tools to fully support the platform.
Not sure who to ask? Feel free to .
How can I help?
If you would like to help develop or test this project, go to the Collaborators tab (after you log in) and request to join. Your help will be appreciated!
Read Me First
A plain-language orientation to Music Rights Management.
If you have just been handed this software and have no idea what it is, start here. Fifteen minutes from now you will know who it is for, what it does, the business it sits in, how to get it running, and what using it looks like on a normal Tuesday. No technical background is assumed, and where something is limited or simulated, this page says so plainly.
A note on the name. The software and this repository call the product Music Rights Management. The sales and marketing materials under
user-docs/go-to-market/call the same product Cadence.
1. Who this is for
The people who administer music rights in small teams — typically one to ten people: independent label owners looking after master recordings, music publishers and publishing administrators looking after compositions, artist managers tracking what their clients are owed, and self-publishing songwriters running their own catalog.
Inside those organisations it serves three jobs: the person keeping the catalog and its ownership correct; the accounting person loading statements, calculating what is owed and paying it; and the rights holder who just wants to log in and see their own splits and earnings.
The assumption throughout is that you are an expert in rights and royalties and not a technologist. Today you are probably doing this with spreadsheets and a few disconnected online tools.
One organisation per installation. Each label or publisher runs its own copy; unrelated companies do not share a system.
2. What it does
It is a single place of record for a music catalog and the money that flows through it.
It holds your catalog — the songs and the recordings of them — and, for each, who owns what percentage of which right, in which country, from which date. Every change to an ownership share becomes a new version; the old one is never lost.
It reads the royalty statements that streaming services, distributors and societies send you, matches each line back to your catalog, and flags what looks wrong.
It then calculates what every rights holder earned — applying the ownership version in force at the time, converting currency at the rate that applied on the day, and recouping outstanding advances — and pays them, with a second person required to approve before money moves.
It generates the standard registration files publishers submit to performing rights societies, and tracks each registration to its answer.
And it writes everything down. Every ownership change, statement, calculation, payment and refused access attempt goes into an audit trail the software itself cannot edit or delete. When an artist asks "how did you arrive at this number?", you can open the exact figure and show the whole chain.
3. The domain: what this business actually is
If you already work in music rights, skip ahead.
Two things, not one
A piece of music is legally two separate properties, owned by different people, earning money in different ways.
The composition — the work, or the song: melody and lyrics. It exists the moment it is written. Owned by the songwriters and their publishers. Identified by an ISWC.
The master recording — the master: one specific recorded performance of that song. Usually owned by the artist and the label that paid for the session. Identified by an ISRC.
One song can have many recordings — the original, an acoustic take, a live version, a cover. Each gets its own ISRC; all point back to one ISWC. Confusing the two is the commonest error in this business, which is why this software keeps them as separate but linked records.
Who gets paid for what
When someone streams a track the money splits down both paths. The recording side is paid by the streaming service or distributor, who send a statement to the label. The composition side is paid partly by performing rights organisations — societies such as ASCAP, BMI, PRS or GEMA — and partly as mechanical royalties. So one play generates two payments, to two sets of people, through two channels, on two schedules. Somebody has to reconcile all of it. That is this software's job.
Why splits, territories and history matter
A song is rarely owned by one person: three co-writers might hold 50/25/25, and each may have signed part of their share to a publisher. Nor is it one number — the same song can split differently for each type of right: performance (played publicly or streamed), mechanical (reproduced), sync (film, TV, advertising) and print (sheet music).
Rights are then bought and licensed country by country. A publisher might control a song worldwide except Japan; different societies collect at different rates and pay in different currencies. So every share here carries a territory (or "Worldwide") and a right type.
And splits change — an option is exercised, rights revert, a dispute settles, a catalog is sold. Overwrite the old percentages and every calculation you already ran becomes unexplainable. This software never overwrites: revising a share creates a new version with an effective date, and the previous version stays. You can ask "who owned this on 3 March two years ago" and get a straight answer. That is what makes an audit survivable.
4. Where it fits: the outside world
Money coming in — statements. Each period, streaming services, distributors and societies send you a file, usually a spreadsheet, listing what your music earned. Every one uses its own columns in its own order. The software ships with ready-made settings for six common sources — Spotify, Apple Music, YouTube Music, DistroKid, TuneCore and CD Baby — and accepts CSV and Excel spreadsheets. For anything else you add your own source and describe where its columns sit, rather than needing new software written. Each incoming line carries a country, a type of use, a gross amount and a currency, and is matched to your catalog principally by ISRC.
Registration going out — performing rights organisations. Publishers must register songs with the societies. The industry format is a CWR file (Common Works Registration, version 2.2), submittable to many societies worldwide. The software generates that file but does not submit it: most societies still take registrations through their own portal or file transfer and offer no connection a system like this could use. You send it their way; when the acknowledgement comes back you import it here and the registration is tracked to its outcome. Any society works — you simply record it as a party of type "PRO".
Money going out — banks and payment providers. By default the payment provider is a sandbox: a stand-in that records a successful payment instantly and moves no real money. That is deliberate — it lets you rehearse the whole workflow safely. Real disbursements use Stripe Connect, which must be configured and each payee connected first. Payout details — bank accounts, routing numbers, tax identifiers — are encrypted before storage, so a stolen copy of the database does not expose them.
Exchange rates, sign-in and email. Statements arrive in many currencies; your organisation settles in one. Daily rates are fetched from the European Central Bank, and the rate used is stored with the calculation forever, so a figure from three years ago can still be re-explained exactly. People sign in with their organisation account (single sign-on) rather than a password held here, and accounts are invite-only — no public sign-up. Email, for invitations and deadline reminders, stays off until outgoing mail is configured.
The identifiers and formats it speaks:
| Thing | What it is |
|---|---|
| ISWC / ISRC | The international codes for a composition and a recording |
| IPI | The number identifying a writer or publisher at the societies |
| UPC / EAN | The barcode identifying a release |
| Country codes | Standard two-letter codes, plus "Worldwide" |
| CWR 2.2 | The file format for registering works with societies |
| CSV / Excel | How statements arrive, and how reports leave |
5. First run: the very first thing to do
Get a copy running with the sample catalog already inside, and click through every screen once. Do not start by loading your own data — look at a worked example first, so you can see what "finished" looks like.
Two ways in. Both need a computer with Docker installed; if that means nothing to you, this is the point to ask whoever manages your computers.
- Option A — the standalone evaluation image (fastest). One package
containing the whole application and its sample catalog; one command starts
it. See
preview/README.md. One honest caveat: by default it expects a real company sign-in, so you need either your organisation's details or the local-only "just let me look around" mode that the same file documents. - Option B — a local installation. Runs the same application from source on
your machine and signs you straight in, no password, as a demonstration
administrator. See
getting-started.mdandgo-to-market/installation-guide.md.
Then, whichever you used:
- Sign in. You land on the dashboard: where the money came from, by country and by how the music was used. If your login is linked to a rights holder, you also get your own earnings.
- Walk down the left-hand menu and just look — Dashboard, Catalog, Rights & Splits, Contracts, Statements, Royalties, PRO Registration, Payments, Admin. The last two appear only for the roles that can use them (section 11).
- Read the seven-minute narrated tour at
../docs/walkthrough-screenshots/script.md; it matches the screens in front of you. - Do the ten-minute hands-on exercise in
getting-started.md, which takes you from creating a songwriter to executing a payment run.
6. Setting up a real working environment
Step 1 — Start clean. A real system starts empty, not with the demo
catalog in it. A dedicated first-use procedure rebuilds the database with only
the reference data every installation needs — countries, use types, and the six
ready-made statement source settings. No people, no songs, no money. Read
production-initialization.md before running
it: it destroys data by design and is meant to be run once, on a new system,
before anybody signs in.
Step 2 — Settle the configuration. Decisions needed before anyone uses it,
all handled by whoever installs the software: where it runs (your machines or a
managed cloud deployment); how sign-in connects to your organisation's account
service; your settlement currency (one for the whole organisation); the
encryption key protecting bank and tax details; whether outgoing email is
on; your payment provider (leave it on the safe sandbox until you are ready for
real money); and how far ahead deadline reminders fire (sixty days by default).
Details in
go-to-market/installation-guide.md and
go-to-market/integration-guide.md.
Step 3 — The first administrator, then the team. The first person to sign in with the configured administrator email address automatically becomes the administrator — nobody creates that account by hand. They then invite everyone else from the Admin screen, set each role, and link each person to their party record so a songwriter sees their own earnings and nobody else's.
Step 4 — Load your catalog, in this order because each step depends on the last: parties (every person and company — songwriters, artists, publishers, labels, distributors, and the societies you deal with), then works with their ISWCs, then recordings with their ISRCs, then link each recording to its work, then group recordings into releases with their barcodes. Fill in ISRCs and ISWCs wherever you can: they are how incoming statements match themselves automatically, and every one left blank is manual work later.
Step 5 — Ownership and contracts. For each work record who holds what percentage of performance, mechanical, sync and print, in which territory, effective from which date; likewise for recordings. Then enter the deals behind those splits — recording agreements, co-publishing and sub-publishing deals, administration and distribution agreements, songwriter and producer agreements, sync and master use licences. Include any advance, so it is recouped before that person is paid — and say what share of each payment goes against it if the deal is not "all of it". Record any administration fee or withholding tax the deal carries: what the contract says is what gets deducted, and a contract that says nothing deducts nothing. Add any option deadlines or reversion triggers too, so you are warned before they pass. Finally, if you receive statements from a source that is not one of the six built-in ones, set it up before the next statement arrives, not during.
7. Day to day
Every time you sign in. Check the dashboard for where revenue is coming from, and open Contracts — any deadline coming up shows as a banner at the top of that screen. (There is no bell icon or message tray. Contract deadlines are the one thing that chases you, and it does so there, plus by email if that is configured.)
As the catalog grows. Add new works and recordings as they are created, link them, and keep the identifier fields filled in. Splits are not a separate list: open the work or recording in the Catalog, then choose Manage splits on that record. When a percentage changes, do not edit the existing share — add a new version with the date it takes effect. You will be asked for a written reason, which is kept in the audit trail. Setting an "as of" date then shows who owned what on any past day. If two people revise the same share at once the second is refused rather than silently overwriting — reload and re-apply. And if shares do not total 100%, the software warns but does not stop you; treat that warning as a to-do list.
When statements arrive:
- On Statements, choose the source, set the period and currency, and upload the file. The same file twice is refused, so revenue cannot be double-counted by accident. Parsing and matching then run on their own and the table refreshes while they work; a row that will not parse is reported as an error without wrecking the rest of the file.
- Open the batch. Every line carries a match status and a confidence score. A line whose ISRC or ISWC matches your catalog exactly is accepted automatically. A line matched only by how similar its title looks is never accepted automatically — it always goes in front of a person, however close the resemblance.
- Work through the proposed and unmatched lines. An assistant suggests the most likely match for each, with a plain-language reason and a confidence score, and offers to confirm the strong ones in one go. It is advisory only — it never applies a match by itself. Section 13 explains what that assistant actually is.
- Confirm or exclude every line before moving on. Clean inputs are the point.
- Check the anomaly flag. The one thing the software watches for is a recording earning far less from a source than it usually does — a hint of under-reporting or missing usage. It needs a couple of earlier statements from that same source before it can say anything.
Working out what is owed. On Royalties, run the calculation for the batches you just cleaned. The engine applies the ownership version in force for that period, converts currency at the rate that applied, and sets earnings against any outstanding recoupable advance before the rest becomes payable. Then open any row's derivation: the statement line, the calculation run, the gross amount, the exchange rate used, the converted amount, the country, the type of use, the exact ownership version applied, the royalty that fell out, and whether it went against an advance rather than being paid. This is your answer to "how did you get this number?", and it is visible to every role, including the writer asking.
Paying people. An accounting user creates a payment run, gathering everything unpaid. A second person must approve it — you cannot approve your own, and your own drafts show "Awaiting second approver" instead of a button, so plan for a second manager to be around. Then execute: every payee is itemised with a provider reference, anyone below their minimum payout is held and carried forward, and a failure is recorded as failed rather than quietly dropped, and can be retried. A rights holder can be shown their remittance — what they were paid, for what.
If you are a publisher. On PRO Registration, pick the society, tick the works, generate the CWR file. Territorial restrictions are carried into the file as "world except those countries". Ineligible works — no title, no writer shares, a writer with no surname, or a restriction naming a territory the software cannot map to an industry code (see §13) — are listed separately with the reason, and the file is still produced for the rest. It appears on screen: copy and save it, then submit it to the society. Import their acknowledgement when it returns and each registration moves to accepted, rejected or conflict.
If you are a songwriter or rights holder. You see only your own works, splits, calculations, earnings and forecast. That is deliberate, not a fault.
8. Ongoing care
Regularly:
- Revenue reports — grouped by country, type of use or currency, exported as a spreadsheet. Note what this is: the gross figures on matched statement lines, answering "where did the money come from?". For "who is owed what", use the royalty summary, which groups calculations by rights holder, right type or currency.
- Forecasts — on Royalties, projected quarterly earnings for a work, recording, rights holder or the whole catalog, with a range and a slider for testing growth assumptions. It needs at least four quarters of real history before producing anything; the range widens the further ahead it looks and is an honest estimate, not a statistical guarantee; and the whole thing is labelled an estimate, never money owed. Do not pay anyone from a forecast.
- Contract deadlines — a daily check looks ahead for option deadlines, reversion triggers and expiries and alerts managers and administrators. Act promptly: once a deadline has actually passed it stops appearing, so an ignored warning goes quiet rather than getting louder.
- Review who has access — remove leavers, and keep everyone on the narrowest role that lets them work.
Quietly in the background: exchange rates are fetched once a day, contract deadlines scanned each morning, and sign-in permissions re-checked every few minutes, so someone removed from your company loses access here within minutes rather than days.
Long term:
- Backups. The database is the system of record — catalog, statements, calculations, payments, audit trail and (depending on configuration) uploaded contract documents. Back it up, and actually test restoring it.
- The encryption key. Back it up separately. If lost or mismatched, bank and
tax fields read as unavailable rather than leaking — it fails safely, but the
data is gone to you. Key rotation is supported; see
useful-commands.md. - The audit trail is permanent and cannot be edited or deleted. That is the feature. Do not look for a way to prune it.
- Personal data requests. A party can be anonymised: contact and banking details removed, financial history and audit entries kept under an anonymous identifier so past accounts still add up.
- Upgrades are a redeploy; the database survives and updates itself.
9. Glossary
| Term | Plain meaning |
|---|---|
| Work (composition) | The song itself — melody and lyrics. Owned by writers and publishers. |
| Recording (master) | One recorded version of a song. Owned by the artist and label. |
| Release | A single, EP or album — recordings sold together. |
| Party | Any person or company in the system: writer, artist, publisher, label, distributor, society, streaming service. |
| ISWC / ISRC | The international codes identifying a work and a recording. |
| IPI | The number identifying a writer or publisher at the societies. |
| Split / share | The percentage of a right that a party owns. |
| Right type | Performance, mechanical, sync or print — the different ways music earns. |
| Territory | The country a share or payment applies to; "Worldwide" for all. |
| Use type | How the music was used: streaming, download, broadcast, sync, and so on. |
| PRO | Performing rights organisation — ASCAP, BMI, PRS, GEMA and the like. |
| CWR | The standard file format for registering works with societies. |
| Acknowledgement | The file a society sends back saying what it accepted or rejected. |
| DSP / distributor | A streaming service; the company that delivers your music to them and passes the money back. |
| Statement / batch / line | The periodic earnings file; one uploaded file as tracked here; one row of it. |
| Match | Connecting a statement line to the recording it refers to. |
| Anomaly | A figure the system thinks looks wrong and wants a human to check. |
| Derivation | The step-by-step explanation of how one royalty figure was reached. |
| Settlement currency | The single currency your organisation calculates and pays in. |
| Advance / recoupment | Money paid up front; earning it back from royalties before payments resume. |
| Cross-collateralisation | Recouping an advance from earnings beyond the works that contract covers — only when the contract says so. |
| Payment run | One batch of payments to many rights holders, created, approved and executed together. |
| Remittance | The statement given to a payee: what they were paid, and for what. |
| Held | A payment kept back for being below the minimum payout, carried forward. |
| Option period / reversion | A window in which a deal can be extended; rights returning to their original owner. |
| Audit trail | The permanent, unalterable record of everything that happened. |
10. The other documents here
In user-docs/:
| Document | For |
|---|---|
getting-started.md | The short version: what it is, how to run it locally, a ten-minute hands-on demonstration. |
production-initialization.md | Preparing a brand-new real system for its first sign-in. The "start clean for real use" path. |
useful-commands.md | Commands for whoever runs the software: starting, stopping, testing, deploying, key rotation. |
api-reference.md, openapi.yaml | For developers connecting other software to this one. |
testing.md | What has been automatically tested, and why the numbers can be trusted. Worth skimming even if you never write code. |
In user-docs/go-to-market/ — the sales and marketing kit, written under
the brand name Cadence: README.md indexes it;
user-guide.md is the plain-language everyday
guide (read this next after this page) and
user-guide-detailed.md the full
reference; installation-guide.md and
integration-guide.md cover standing it
up and connecting it to the outside world;
technical-documentation.md is for a
technical evaluator; messaging.md,
sales-enablement.md and
advertising-copy.md are positioning and
copy; white-papers/ holds four longer pieces
(royalty accuracy and reconciliation; rights and splits for independents;
statement ingestion; payments, recoupment and transparency); and
../website/index.html is a self-contained landing page.
Elsewhere: ../preview/README.md (the evaluation
image and its sample data) and
../docs/walkthrough-screenshots/ (the
narrated tour with screenshots).
11. Who can do what: the six roles
Every user has one role, and the roles are a ladder — each can do everything below it, plus more.
| Role | In plain terms |
|---|---|
| Viewer | Look, change nothing. |
| Writer | A songwriter or rights holder. Sees only their own works, shares, calculations, earnings and forecasts. |
| Publisher | Manages the catalog: creates works, recordings and releases, sets and revises ownership shares, generates society registrations. Still narrowed to their own records if linked to a party. |
| Accounting | Plus the money: uploads statements, resolves matches, runs calculations, enters exchange rates, creates and executes payment runs. Sees the whole organisation's figures. |
| Manager | Plus creating parties and contracts, approving payment runs, inviting people, and reading the audit trail. |
| Admin | Everything, plus changing roles, deactivating accounts, deleting records and anonymising parties. |
Three rules worth remembering:
- Whoever creates a payment run cannot approve it. Approval always needs someone else at manager level or above.
- A user linked to a party sees only that party's data, unless their role is accounting or higher. Records they cannot see simply do not appear, rather than showing a "no access" message.
- Reaching accounting level removes that narrowing. Do not hand out the accounting role just so someone can upload one file — it also shows them everyone's earnings.
PRO Registration (publisher and up) and Admin (manager and up) are hidden from the menu unless your role can use them. Elsewhere a button may be visible that your role cannot complete; the refusal comes when you press it.
12. Sample data, and how to start fresh
What ships in the evaluation image: a complete worked example, already loaded — a fictional catalog touching every screen so nothing looks empty. Songwriters, artists, publishers, labels and societies as parties; songs and recordings, linked and grouped into releases with barcodes; ownership splits across the different right types, including some revised more than once so you can see version history working; contracts with partly-recouped advances; royalty statements from several sources, already parsed, matched and calculated, with some lines deliberately left unmatched or flagged so you can practise resolving them; and completed payment runs, including a held payee and a failed payment.
Everything is invented. The people, songs, artists, publishers and labels are fictional and correspond to no real person or company. The only real names are the streaming services, distributors and societies, because keeping those recognisable is what makes the demonstration make sense. Dates are anchored to the day you run it, so the demo never looks stale.
Starting fresh, for real use. An evaluation copy resets itself each time
you start a fresh container unless you deliberately keep the data — see
../preview/README.md. For a system you will actually
use, the correct path is the first-use initialisation in
production-initialization.md: it rebuilds the
database with only the reference lists every installation needs — countries,
use types, the six statement source settings — and nothing else. No fictional
people, no fictional money, not even an administrator account.
There is also a demo data loader for deliberately filling a test or demonstration environment. It always makes you name the environment explicitly and refuses anything named as production without an override. Never point it at a real system.
13. Common questions and gotchas
I uploaded a statement and nothing is happening. Statement processing is handed to a background helper process. If that process is not running, the batch just sits there. This is the commonest "it's broken" report — ask whoever runs the software to check the worker is up.
A payment completed instantly but no money moved. Expected. The default provider is a safe stand-in that simulates success so you can rehearse the workflow. Real transfers need a real provider configured.
The match suggestions feel a bit mechanical. They probably are. Out of the box the assistant is a simulated one that ranks candidates by how similar the titles and artist names look — deterministic and entirely offline. A genuine AI assistant is used only when an access key has been configured. Either way it is advisory, never applies a match on its own, and is only ever sent titles, artist names and identifiers — never amounts, never anyone's personal or banking details.
I can't approve my own payment run. Correct, and not configurable. Money never leaves on one person's say-so.
A payee shows as "held", or bank details show as unavailable. Held means either the amount is below their minimum payout (it carries forward), or their payout details could not be read — usually an encryption key that does not match the one the details were saved under. That same mismatch is what makes bank and tax fields read as unavailable: the software deliberately shows nothing rather than guessing or leaking. Fix the key.
My change to a split was rejected. Somebody else revised the same share while you were working. Reload and apply your change to the latest version — this is what stops two people silently overwriting each other.
I typed a title wrong. How do I edit the record? You can't, from the screens. This build lets you create catalog records but has no edit form and no delete button for them. Get names and identifiers right first time, and have someone technical correct anything that slips through. Ownership splits are the deliberate exception: those you revise, and every revision is kept.
The contract screen asked me for something that looks like computer code. It did. Contract terms — rates, advances, option dates, reversion clauses — are entered as structured text rather than a friendly form. Get whoever set up the system to build the first contract of each type, then copy its shape.
I generated a registration file but there is no download button. Correct — it is displayed on screen; select, copy and save it before submitting.
A territory-limited song was left out of my registration file. This should be rare now. A song whose ownership covers everywhere goes out as worldwide; one whose ownership stops at certain borders goes out as "world except those countries". Writing that exclusion needs each country's industry code, and those codes now ship filled in for all 249 individual countries, so ordinary territorial deals register correctly with nothing for you to load. If a song is still left out, the reason names a territory the software could not map — most likely one added by hand without a code. That refusal is deliberate: better a stated omission than a song quietly registered worldwide against a limited deal.
My registration file would not generate at all: it asked for an IPI.
Every registration file has to say who is submitting it, using the publisher's
IPI name number. If no publisher in the system has one recorded, the software
stops and tells you to add it rather than sending a file the society cannot
attribute. Add ipi_name_number to the publishing party (or link your own
account to a publisher that has one) and try again.
What happens if I calculate the same statements twice? The second run replaces the first rather than adding to it. The earlier figures are marked as superseded — kept and still viewable as history, never deleted — and the recoupment they took is handed back to the advance before the new run reads the balance. So the rights holder is paid once, at the newer figures, and the advance reflects only the calculation that now counts.
It refused to recalculate: it says the batch has already been paid. That is the guard working. Once a calculation has gone out in a payment run, the money has left the building and cannot be recalculated away. Correct it with an adjustment — a compensating entry — instead. Note the flip side: a payee whose payout was held below their minimum has not actually been paid, so their batch can still be recalculated; the held item then refers to superseded figures, but it disbursed nothing and the next payment run uses the live ones.
A line vanished from the payable figures after I recalculated. Check whether it went held — a missing exchange rate is the usual cause. Its earlier figures were superseded and the recalculation produced nothing to replace them, so the line is simply not payable until you add the rate and recalculate the batch again.
Where did the rest of my catalog go? Long lists show the first hundred or two hundred rows and say so; there are no page-forward controls. Use the search box on the Catalog screen.
Where do I see notifications? There is no bell icon or message tray. Contract deadlines appear as a banner on Contracts, and by email if that is switched on. Everything else confirms itself on the screen where you did it.
The forecast refuses to produce anything. It needs at least four quarters of real earnings history, and will not guess from less.
Someone cannot sign up. There is no public sign-up. An administrator invites them by email; they sign in with their organisation account and are linked automatically.
Does it register songs with the society, or read the industry XML formats? Neither. It produces the standard registration file and you submit it through the society's own channel, as most societies still require. Statements come in as CSV or Excel only — no DDEX or similar.
Can I connect my own systems? Can two companies share one installation? Can I
pay in several currencies?
No, no and no. Programmatic access keys are future work — everything happens on
behalf of a signed-in person in a browser (see
api-reference.md). One organisation per installation. One
settlement currency, though the payment provider will convert at the point of
payment if a payee's account needs a different one.
14. Where to get help
First, your own administrator. Access, roles, invitations, configuration and anything switched off are theirs to fix. If a screen or button described here is not visible to you, it is almost always a role question.
Then, the community at wbsp.ai. This software is a core build — it does the real work, but deliberately carries no company branding, waiting for your name, your colours and your wording. It was built as part of an open initiative, and wbsp.ai is where you go to ask questions and make suggestions; to find people who customise applications like this one for a living, if you want it shaped around how your business actually runs; and to browse the other versions of this application, and hundreds of others, that the community has already built — one may be closer to what you need than this one.
If you know this industry and are comfortable working with AI tools, you can also change it yourself. That is what it was designed for.
Next: go-to-market/user-guide.md for the
everyday walkthrough, or getting-started.md to try the
ten-minute exercise.
Configuration
What this application asks for when somebody installs it. These are the questions, not anyone's answers — no values are held or shown here.
People sign in to this application. The hosting platform registers the sign-in for you when you install it, so there is nothing to set up yourself.
You will be asked for 4 things
- Anthropic API key (only for the live Claude reconciliation assistant)
ANTHROPIC_API_KEYWhere to get this - Stripe secret key (only if payouts run through Stripe Connect)
STRIPE_SECRET_KEYWhere to get this
smtp
Optional, and all or nothing — supply every part or skip the whole set. A half-configured integration is refused at install time.
- SMTP password
SMTP_PASSWORD - SMTP username
SMTP_USERNAME
Supplied automatically — no typing needed
The hosting platform provides these when the application is installed, either by generating them or because it already knows them.
- AUTH_HAP_ID
- AUTH_HAP_ISSUER
- AUTH_HAP_SECRET
- AUTH_URL
- ENCRYPTION_KEY
- SECRET_KEY












