Skip to main content

WAI Extension: Play Royalties

Mirrored from the canonical text at commit 498e6b88 ().

Status: Draft. Registers the record wai.delivery.play_royalties: what a service’s plays of recordings give each holder of a share in the works recorded, as a statement anyone holding the signed records recomputes. A listener’s device signs a play receipt (wai-play) for each play, under a key made for one subscriber and one period and bound to the subscriber’s entitlement of key-release by the entitlement’s holder key: it names the recording by a works document of music-rights and its position, the milliseconds played, a region aggregated as WAI aggregates one, and the delivered objects it presented, by the content hashes jwp-receipts names them by. The service signs a pool (wai-royalty-pool): its period, currency and amount, the invoices of receipt-ledger the amount is computed from where it names them, the model (pro_rata or user_centric), every threshold a play and a recording meet to count, the multipliers, and the listeners it excludes, each with its reason. A ledger signs a statement (wai-royalty-statement): one counted-plays table, the pool divided over it in integers with the largest-remainder rule revenue-share divides by, each recording’s part divided among its works, and each work’s part among the holders of right-shares’ view of its key, where a view in conflict goes to a suspense line, never paid and never resolved, and money no stated share reaches goes to an unallocated line that says why. A verifier given the receipts recomputes every figure and refuses a statement that does not recompute; one given no receipts checks the statement against its own aggregates and says so. No new transport, no payment and no legal rule: a statement is the figures a payment rests on, and how they are checked. The reference implementation is the play_royalties module of wai-rs (feature play_royalties); the corpus is live-conformance/play-royalties/, and its second implementation is live-conformance/play_royalties_verify.py. Keywords MUST, MUST NOT, SHOULD, MAY are RFC 2119/8174.

Texts read for this revision: the WAI texts this one cites, as merged on 14 November 2026; RFC 8032; RFC 8259; RFC 8785; FIPS 180-4. Decision D139 records the choices this text makes and why.

1. Scope

In scope: the play receipt, its binding to an entitlement and its digest and signature (§3); the pool, its thresholds, multipliers, exclusions and funding (§4); which plays count and the counted-plays table (§5); dividing the pool over the table under each model, a recording’s part among its works and a work’s part among its holders, with the suspense and unallocated lines (§6); the statement (§7); its verification from the receipts or from its aggregates (§8); and what a statement does not show (§9).

Out of scope: paying anyone, an account a payment reaches, and converting a currency; what a subscriber pays and how a service sets a pool’s amount or rate, which a pool states and this text does not choose; whether a holder is entitled to what a share statement states, which right-shares §1 leaves out too; resolving a conflict between share statements; shares of a recording’s own rights (its sound recording, as distinct from the works it is a performance of), which no WAI record states in this revision; how a device decides that a person listened; and every legal effect of a pool or a statement. WAI texts set no legal rules: this extension states what a statement carries and how it is checked, not what anyone is owed under any law or contract.

Relationship to the core spec: wai.delivery.play_royalties is a record (SPEC §5): signed records a WAI tool emits and verifies. It names no payload format and is not dispatchable.

Relationship to the texts it reads: a play receipt names a works document by its digest (music-rights §5.2), an entitlement by its digest (key-release §5.2) and objects by their content hashes (jwp-receipts §2.1); a pool names invoices by their digests (receipt-ledger §6.7); a statement reads views of right-shares §5.2. It changes none of their records, rules, corpora or reasons.

2. Terms

3. The play receipt

3.1 The receipt

A play receipt states one play of one recording. It is a document of exactly these members:

memberform
kind"wai-play"
version1
listenera key: the listener, which signs the receipt
start, endtimes, start below end: the period the listener is for
entitlement64 lowercase hexadecimal digits: the digest of the subscriber’s entitlement
bindinga signature: by the entitlement’s holder key (§3.2)
works64 lowercase hexadecimal digits: the digest of a works document
recordingan integer: the position from 0 of the recording in that document’s recordings
ata time, from start (included) to end (excluded): when the play began
played_msan integer from 1: the milliseconds of the recording presented
regiona region code, or null where the device does not state one
context"chosen" where the listener chose the recording, "programmed" where the service chose it, or null where the device does not state which
objectsan array of 1 to 512 content hashes, in strictly ascending order: the delivered objects the play presented
siga signature by listener (§3.3)

region is the code the device aggregates its own location to before anything leaves it, as audience-decision §4.3 aggregates a session’s: a receipt carries the code and no more. A receipt states a play of the subscriber its entitlement names, and a device signs one receipt for each play; two plays that began at one instant are two receipts only where some member differs.

3.2 The binding

The binding ties a listener to one entitlement for its period. It is Ed25519 by the entitlement’s holder key over wai:play-listener (ASCII) and 0x01, followed by the canonical form of the document of exactly the receipt’s entitlement, listener, start and end, verified strictly as SPEC §7 Signatures verifies every signature. Every receipt of one listener in its period carries the same binding. The device that holds the holder key makes a listener when a period begins and signs its one binding for that period.

3.3 Digest and signature

The digest of a receipt is SHA-256 over the canonical form of the receipt without sig, written as 64 lowercase hexadecimal digits. Its signature is Ed25519 by listener over wai:play (ASCII) and 0x01, followed by that same canonical form, verified strictly as SPEC §7 Signatures has it. A receipt is named by its digest.

4. The pool

4.1 The pool

A pool states the money a service divides by plays in one period, and every rule it divides by. It is a document of exactly these members:

memberform
kind"wai-royalty-pool"
version1
servicea key: the service, which signs the pool
start, endtimes, start below end: the period
currencythree capitals A–Z: an alphabetic currency code of ISO 4217
amountan amount from 1: what the pool divides
fundingnull, or an object of exactly invoices and rate_ppm (§4.4)
model"pro_rata" or "user_centric" (§6.2, §6.3)
contributionsnull under pro_rata; under user_centric, an array of 1 to 65 536 objects of exactly listener (a key) and amount (an amount from 1), in strictly ascending order of listener (§6.3)
share_typea share type (right-shares §3): the share of a work the pool pays
righta right type (right-shares §3): the right the plays use
authoritiesan array of 1 to 64 keys, in strictly ascending order: the entitlement authorities whose entitlements a receipt may cite
publishersan array of 1 to 64 keys, in strictly ascending order: the keys whose group receipts may deliver a play’s objects
regionsnull, or an array of 1 to 8 192 region codes in strictly ascending order of their bytes: the regions whose plays the pool counts
qualifying_msan integer from 1: the least played_ms that counts a play
min_playsan integer from 1: the least counted plays a recording needs
min_listenersan integer from 1: the least distinct listeners a recording’s counted plays need
listener_capnull, or an integer from 1: the most plays of one listener the period counts
multipliersan array of 0 to 2 objects of exactly context ("chosen" or "programmed") and weight (an integer from 2 to 1 000), in the order chosen, programmed, each context at most once
below"redistribute" or "unallocated": where the part of a recording below a threshold goes (§6.1)
excludedan array of 0 to 65 536 objects of exactly listener (a key) and reason, in strictly ascending order of listener
siga signature by service (§4.5)

A pool divides money for one share type and one right: a service that pays two rights divides two pools.

4.2 Thresholds and multipliers

Every threshold is a member of the pool, and the service signs it: qualifying_ms for a play, min_plays and min_listeners for a recording, listener_cap for a listener, and regions for where a play was. A threshold of 1, and null for listener_cap and regions, leave nothing out. A play’s weight is the weight of the multiplier whose context is the receipt’s, and 1 where the pool lists none for it, or where the receipt’s context is null. A weight multiplies a play in the table (§5.2); it never makes a play count that does not.

4.3 Exclusions

The pool lists each listener whose plays it does not count, with the service’s reason: "artificial" (plays the service found not made by a person listening), "test" (a key of the service’s own testing), "refunded" (a subscription whose fee was returned) or "other". An exclusion is the service’s statement, signed; a verifier checks that it was applied as listed and that its money is on a line of its own (§6.3), not why it was made.

4.4 Funding

funding null states that amount is the service’s figure, which no record the pool names computes. Otherwise invoices is an array of 1 to 256 digests of invoices, in strictly ascending order, and rate_ppm an integer from 1 to 10⁶; then amount is ⌊S × rate_ppm / 10⁶⌋, where S is the sum of the invoices’ amount, and each invoice is one the service sold, in the pool’s currency, for a period within the pool’s (§8.2 step 3). A verifier holding the invoices recomputes the amount from them.

Under user_centric, the contributions sum to exactly amount: they are how the service divides the pool among its subscribers, one contribution for each listener, and a subscriber that knows its own listener checks its own line. A pool may list a contribution of a listener no receipt names (§6.3).

4.5 Digest and signature

The digest of a pool is SHA-256 over the canonical form of the pool without sig, and its signature is Ed25519 by service over wai:royalty-pool (ASCII) and 0x01, followed by that canonical form, verified strictly (SPEC §7 Signatures).

5. Counting

5.1 Which plays count

The receipts of a pool are taken in ascending order of (at, digest). Each is, at the first of these that applies:

  1. excluded: its listener is listed in the pool’s excluded;
  2. short: its played_ms is below qualifying_ms;
  3. region_unknown: the pool’s regions is not null and the receipt’s region is null; region_outside: the pool’s regions is not null and does not hold the receipt’s region;
  4. capped: listener_cap is not null and listener_cap receipts of its listener, earlier in this order, are counted;
  5. otherwise counted, with its weight (§4.2).

A receipt that is not counted is still a receipt the statement rests on: the statement states how many of each class there are (§7.1, uncounted). A cap is applied in the order of the plays, so the plays past it are a listener’s latest.

5.2 The counted-plays table

The table has one row for each recording with at least one counted play, in ascending order of (works by its bytes, recording). A row states:

Under user_centric the table also has its listening: for each listener with at least one counted play, in ascending order of the listener, that listener’s rows, each a recording with its plays and weighted of that listener alone, in the table’s order. A row’s plays and weighted are the sums of the listening’s, and its listeners the number of listeners whose listening names it.

The table is one table for both models: the thresholds read it, every division reads it, and a verifier given no receipts reads the statement’s copy of it (§8.3).

6. Dividing the pool

6.1 The division

A division of an amount A among parts with integer weights w₁ … wₙ, each at least 1, in their order, gives each part an integer, and the integers sum to A exactly. With W the sum of the weights:

  1. each part’s quota is A × wᵢ, its base ⌊quota / W⌋, and its remainder quota − base × W;
  2. the leftover is A less the sum of the bases, which is less than n;
  3. the parts with the largest remainders, as many as the leftover, each receive one more than their base; between equal remainders, the earlier part receives it first.

This is revenue-share §7.3’s largest-remainder rule with weights that need not sum to 10⁶. Each division rounds once: its parts are floors, and the residue goes by the remainders. No play is ever valued alone, so rounding does not accumulate over plays.

The division set is the rows a model divides over: under below "redistribute", the rows whose status is counted, so a recording below a threshold takes no part and the others share what its plays would have taken; under "unallocated", every row, and the part of a row below a threshold goes to its below_threshold line (§6.6), so the counted recordings take only what their own plays give them.

6.2 Pro rata

The pool’s amount is divided among the rows of the division set, each weighted by its weighted, in the table’s order. A pool whose division set has no row gives its whole amount to the no_plays line.

6.3 User-centric

Each contribution, in the pool’s order, is divided by itself:

  1. a contribution of an excluded listener goes to the excluded line;
  2. a contribution of a listener whose listening names no row of the division set goes to the no_plays line;
  3. otherwise the contribution is divided among the rows of the division set its listener’s listening names, each weighted by that listener’s weighted, in the table’s order.

A row’s part is the sum of the parts every contribution gives it. A listener with a counted play has a contribution (§8.2 step 8): the model divides each subscriber’s money by its own plays, and a play no contribution pays for is a play of nobody the pool funds.

6.4 A recording among its works

A row whose status is counted gives its part to its recording’s works: divided among them in equal weights, in the order the recording’s works names them; a recording whose works document names no work for it gives its part to its no_work line. A works document states no share of a recording among its works, so equal weights are this revision’s rule. A work’s part is the sum of the parts its recordings give it.

6.5 A work among its holders

The holders of a work are those of the view of the key (the work, the pool’s share_type, the pool’s right) that combining the share statements given for its works document gives (right-shares §5.2). For each work with a part, in ascending order of (works by its bytes, work):

  1. No statement. No statement given for its works document states the key: its part goes to its no_statement line.
  2. Suspense. The view’s status is conflict: its part goes to its suspense line. A suspense line pays no claimant and resolves nothing: the claims stay as right-shares §5.3 leaves them. The statement states the money held for the work; who claims it is the view’s, from the share statements given.
  3. Holders. Otherwise the part is divided among the view’s agreed parties whose share is not null, in the view’s order, weighted by their shares, and then, where the view’s remainder is above 0, the remainder, weighted by it. Each party’s part is its payments line; the remainder’s part is the work’s remainder line: the share of agreed parties whose share is not known, and of the right no party claims.

A share not known is never paid as 0 and never shared out among the shares that are known: its money is on the remainder line, as right-shares §4.1 keeps it in the remainder.

6.6 The lines

Every unit of the pool’s amount is on exactly one line:

reasonnameswhat it holds
no_playsnothinga pro rata pool whose division set has no row; under user_centric, the contributions of listeners whose listening reaches no row of it
excludednothingunder user_centric, the contributions of excluded listeners
below_thresholda recordingunder below "unallocated", the part of a row below a threshold
no_worka recordingthe part of a counted recording whose works document names no work for it
no_statementa workthe part of a work no share statement given states the key of
remaindera workthe part of a view’s remainder

A line stands wherever what it holds stands, whatever its amount: a remainder line for every work with a part whose view has a remainder above 0, a payment for every agreed party with a share, and an unallocated line of each kind the division gives part of the pool to, so that a reader sees every holder and every share not known even where a part rounds to 0. Payments are in ascending order of (works, work) and then the view’s order; suspense lines in ascending order of (works, work); unallocated lines in the order of the table above, and within a reason in ascending order of (works, recording) or (works, work).

7. The statement

7.1 The statement

A statement states the division of one pool. It is a document of exactly these members:

memberform
kind"wai-royalty-statement"
version1
ledgera key: the ledger, which signs the statement
pool64 lowercase hexadecimal digits: the pool’s digest
worksan array of 0 to 1 024 digests, in strictly ascending order: the works documents the table’s rows name
receiptsan object of exactly count (an integer) and digest (64 lowercase hexadecimal digits): the receipts the statement rests on (below)
uncountedan object of exactly excluded, short, region_unknown, region_outside and capped, each an integer: the receipts not counted, by class (§5.1)
recordingsan array of 0 to 65 536 rows, each an object of exactly works, recording, plays, weighted, listeners (each of plays, weighted and listeners an integer from 1), status and amount (an amount)
listeningnull under pro_rata; under user_centric, an array of 0 to 65 536 objects of exactly listener (a key) and rows (an array of 1 to 65 536 rows), each row an object of exactly works, recording, plays and weighted (each of plays and weighted an integer from 1)
paymentsan array of payments (§6.6), each an object of exactly works, work, name (a text), isni (a string or null), share (ppm from 1 to 10⁶) and amount
suspensean array of suspense lines, each an object of exactly works, work and amount
unallocatedan array of unallocated lines, each an object of exactly reason and amount, with works and recording or works and work where §6.6’s table names them
sumsan object of exactly payments, suspense and unallocated: each kind’s lines summed
siga signature by ledger (§7.2)

A row’s amount is its part of the division under §6.2 or §6.3 where its status is counted, and 0 where it is not: a row below a threshold takes no part, and its plays’ money is either shared by the counted rows or on its below_threshold line, as the pool’s below says. The three sums add to the pool’s amount.

receipts commits to every receipt the table was counted from, counted or not: count is their number, and digest SHA-256 over wai:royalty-receipts (ASCII) and 0x01, followed by each receipt’s digest (32 bytes) in strictly ascending order. A ledger that later discloses the receipts discloses exactly these; one that drops a receipt changes the digest.

7.2 Digest and signature

The digest of a statement is SHA-256 over the canonical form of the statement without sig, and its signature is Ed25519 by ledger over wai:royalty-statement (ASCII) and 0x01, followed by that canonical form, verified strictly (SPEC §7 Signatures).

8. Verification

8.1 Inputs

A verifier is given one verification document, a JSON object of exactly these members:

membervalue
poolthe pool’s text
statementthe statement’s text
invoicesan array of invoices, each its bytes in lowercase hexadecimal
worksan array of objects of exactly text (a works document’s text) and package (exactly pack_digest and components: the package it names, music-rights §5.3)
sharesan array of objects of exactly works (a works document’s digest) and statements (an array of share statements’ texts, in order)
receiptsnull where the receipts are not disclosed; otherwise an object of exactly plays (an array of play receipts’ texts), entitlements (an array of entitlements, each its bytes in lowercase hexadecimal), groups (an array of group receipts) and objects (an array of object receipts)

8.2 Steps

It refuses at the first that applies, with the reason and where (at, the path of the input):

  1. royalty_document_malformed, at document: the document is not of §8.1’s form.
  2. The pool, at pool: pool_malformed when its text holds more than 4 194 304 bytes, is not a document, or its members are not exactly §4.1’s, each of its form, contributions null exactly under pro_rata; pool_signature_invalid when its signature does not verify; pool_contributions_mismatch when, under user_centric, the contributions do not sum to amount.
  3. The funding, where it is not null, each invoice in the order invoices names them, at pool, funding and its position: pool_invoice_missing when no invoice given has that digest (SHA-256 over its bytes before its last 64); pool_invoice_invalid when it does not read by receipt-ledger §6.8, its signature among its rules; pool_invoice_foreign when its seller is not the pool’s service, its currency not the pool’s, or its period not within the pool’s. Then, at pool, pool_amount_mismatch when amount is not §4.4’s.
  4. The statement, at statement: statement_malformed when its text holds more than 16 777 216 bytes, is not a document, or its members are not exactly §7.1’s, each of its form; statement_signature_invalid when its signature does not verify; statement_pool_mismatch when pool is not the pool’s digest.
  5. The works documents, each in order, at works and its position: verified against its package by music-rights §5.3, that text’s reason; royalty_document_malformed when its digest is an earlier one’s. Then, at statement, statement_works_missing when the statement’s works names a digest no works document given has.
  6. The share statements, each group in order, at shares and its position: shares_works_unknown when its works is not the digest of a works document given, and royalty_document_malformed when it is an earlier group’s; then its statements combined over that works document and its package by right-shares §5.2, a refusal being that text’s reason with the position of the statement after statements.
  7. The receipts, where they are given:
    1. each entitlement, at receipts, entitlements and its position: entitlement_invalid when it does not hold (key-release §5.2); entitlement_foreign when its authority is not one of the pool’s authorities;
    2. each group receipt, at receipts, groups and its position: delivery_invalid when it does not read or its signature does not verify (jwp-receipts §3, steps 1 and 2); delivery_foreign when its signer_pubkey is not one of the pool’s publishers;
    3. each object receipt, at receipts, objects and its position: delivery_invalid when it does not read, or no group receipt given of its track_alias and group_id holds it by its proof (jwp-receipts §3, steps 4 and 5);
    4. each play receipt, in order, at receipts, plays and its position:
      • play_malformed: its text holds more than 65 536 bytes, is not a document, or its members are not exactly §3.1’s, each of its form;
      • play_signature_invalid: its signature does not verify by its listener;
      • play_duplicate: its digest is an earlier receipt’s;
      • play_period_mismatch: its start and end are not the pool’s;
      • play_entitlement_missing: no entitlement given has its entitlement as digest;
      • play_binding_invalid: its binding does not verify by the entitlement’s holder key;
      • play_not_entitled: ⌊at / 10⁶⌋ is before the entitlement’s not_before or after its not_after;
      • play_listener_conflict: an earlier receipt binds its listener to another entitlement, or its entitlement to another listener;
      • play_recording_unknown: its works is not the digest of a works document given, or its recording not the position of one of that document’s recordings;
      • play_longer_than_recording: its played_ms is above the recording’s length;
      • play_not_delivered: one of its objects is not the content_hash of an object receipt given.
  8. The figures, at statement. The table is counted from the receipts (§5) where they are given, and is the statement’s recordings and listening where they are not.
    1. contribution_missing, at pool: under user_centric, a listener of the table’s listening has no contribution.
    2. With the receipts: statement_receipts_mismatch when receipts is not their count and digest (§7.1); then statement_table_mismatch when works, uncounted, the rows but their amount, or listening are not those counted. Without them: statement_table_mismatch when the statement’s table does not hold together: the rows are not in §5.2’s order, each recording once, or a row’s works and recording are not a recording of a works document given, its status is not the one §5.2 gives its plays and listeners, its weighted is below its plays or above its plays times the pool’s largest weight, its listeners above its plays, works is not the rows’ works documents, or listening is not null exactly under pro_rata and, under user_centric, is not in §5.2’s orders or does not sum to the rows as §5.2 says.
    3. statement_lines_mismatch when a row’s amount, a line, the order of the lines or sums is not what §6 gives over the table.

8.3 Outcome

On the basis aggregates, a verifier has checked the division, the thresholds against the rows, the works and the holders’ shares, and that every unit of the pool is on a line: it has not checked that the rows are what any receipt states, and it says so. A ledger that cannot disclose the receipts to a reader discloses the statement, whose receipts commits to them, so that a later check against them is of the same receipts.

9. What a statement does not show

10. Reasons

reasonraised at
royalty_document_malformed§8.2 steps 1, 5 and 6
pool_malformed§8.2 step 2
pool_signature_invalid§8.2 step 2
pool_contributions_mismatch§4.4, §8.2 step 2
pool_invoice_missing§8.2 step 3
pool_invoice_invalid§8.2 step 3
pool_invoice_foreign§4.4, §8.2 step 3
pool_amount_mismatch§4.4, §8.2 step 3
statement_malformed§8.2 step 4
statement_signature_invalid§8.2 step 4
statement_pool_mismatch§8.2 step 4
statement_works_missing§8.2 step 5
shares_works_unknown§8.2 step 6
entitlement_invalid§8.2 step 7
entitlement_foreign§8.2 step 7
delivery_invalid§8.2 step 7
delivery_foreign§8.2 step 7
play_malformed§8.2 step 7
play_signature_invalid§8.2 step 7
play_duplicate§8.2 step 7
play_period_mismatch§8.2 step 7
play_entitlement_missing§8.2 step 7
play_binding_invalid§3.2, §8.2 step 7
play_not_entitled§8.2 step 7
play_listener_conflict§8.2 step 7
play_recording_unknown§8.2 step 7
play_longer_than_recording§8.2 step 7
play_not_delivered§8.2 step 7
contribution_missing§6.3, §8.2 step 8
statement_receipts_mismatch§7.1, §8.2 step 8
statement_table_mismatch§5.2, §8.2 step 8
statement_lines_mismatch§6, §8.2 step 8

A verifier also gives music-rights’ reasons for a works document it refuses (§8.2 step 5) and right-shares’ reasons, with music-rights’ for an ISNI, for a share statement it refuses (§8.2 step 6).

11. Conformance

live-conformance/play-royalties/ holds the corpus, in one file, vectors.json, written from fixed seeds by wai_play_royalties_vectors gen. It holds each record once, by name: two works documents with their packages and a third no play names; the share statements over the first two, the second’s two statements in conflict over one work; four subscribers’ entitlements and a fifth’s; the group and object receipts of each of six recordings’ three objects; fifteen play receipts of one month by four listeners; two invoices of the service in one chain; nine pools and their statements; and the altered copies the refused cases need. Each case names the records of one verification document (§8.1), and the member it drops where it drops one, with its outcome (§8.3) and its class: accepted for a statement recomputed from the receipts with an amount recomputed from invoices, gap for one checked against its aggregates or with an amount the service states, and refused. Every figure of a statement, every row, part, line and sum, is declared by hand in the generator and never copied from the reference, which must then accept it and state it itself, byte for byte, from the same receipts.

wai_play_royalties_vectors verify and the test tests/play_royalties.rs check that the file regenerates byte for byte, that wai-rs gives every case its outcome and class, that every reason of §10 is some case’s, and that §10 lists exactly the reference’s reasons; the module’s own tests require the reference to state each accepted statement the corpus declares. live-conformance/play_royalties_verify.py is the second implementation, written from this text and sharing no code with wai-rs: it takes documents from route_record_verify.py, works documents from music_rights_verify.py, views from right_shares_verify.py, entitlements from key_release_verify.py, group and object receipts from jwp_verify.py and invoices from receipt_ledger_verify.py, and writes everything this text adds itself: the receipt, the pool, the statement, counting, every division and every line. It gives every case its outcome, requires every mutated copy of the corpus to fail, and drops each of its own checks in turn and requires the corpus to catch the weakened verifier. Each condition of §8.2 is a check of its own, and a check no case makes refuse is named and must be caught by the checks no vector carries.

12. Security and privacy considerations