foley.provenance#

Provenance layer for foley — attribution/credits (and, later, disclosure).

This subpackage keeps published output legal and traceable. Its first half (#9a) is foley.provenance.credits — the stdlib-only TASL attribution / credits generator (CREDITS.md + JSON manifest) that reads the LicenseRecord SSOT.

Its second half (#9b) is foley.provenance.disclosure — AudioSeal watermarking, the portable C2PA content-credential sidecar, the EU AI Act Art. 50 checklist, and the trademarked-audio / recognizable-voice safety scan. It is intentionally NOT imported here so import foley stays dependency-light: its module top level is stdlib-only, but audioseal / torch / torchaudio (the foley[provenance] extra) are imported lazily inside its watermark functions. Import it explicitly (from foley.provenance import disclosure) or reach the pure helpers via foley.art50_checklist / foley.scan_prompt.

Functions

`attribution_line`(source, *[, fmt])	Render one sound's TASL attribution line.
`credit_entry`(record, *[, title])	Build a `CreditEntry` from a record (title override optional).
`credits_for`(sounds, *[, title, ...])	Build the deduplicated `Credits` for the sounds used in a run.
`credits_manifest`(credits)	The machine-readable manifest for `credits` — a JSON-native dict.
`render_credits_md`(credits, *[, title, ...])	Render `credits` as a deterministic `CREDITS.md` document.

Classes

`CreditEntry`(sound_id[, title, author, ...])	One rendered TASL credit for a single sound (a flat, serializable row).
`Credits`([entries, title, schema_version])	A deduplicated, ordered collection of `CreditEntry` for one run.

class foley.provenance.CreditEntry(sound_id, title=None, author=None, author_url=None, source=None, source_url=None, license_id='unknown', license_name=None, license_url=None, modified=False, requires_attribution=False, attribution_text=None, notice_text_required=None, is_ai_generated=False, generator_model=None, disclosure_recommended=False, watermark=None, c2pa_manifest_ref=None)[source]#

Bases: SerializableMixin

One rendered TASL credit for a single sound (a flat, serializable row).

Built by credit_entry() from a record’s rights fields; rendered to a single attribution line by attribution_line(). Carries the AI-disclosure

watermark / C2PA fields as pass-throughs so the JSON manifest becomes the content-credentials carrier once #6/#9b populate them (None today).

class foley.provenance.Credits(entries=(), title='Credits', schema_version=1)[source]#

Bases: SerializableMixin

A deduplicated, ordered collection of CreditEntry for one run.

Iterable and sized; renders to CREDITS.md via markdown and to a JSON manifest via manifest (== to_dict()). Both are deterministic (no timestamps) and diffable.

property manifest: dict#: The machine-readable JSON manifest (a plain dict).

property markdown: str#: The rendered CREDITS.md document.

foley.provenance.attribution_line(source, *, fmt='markdown')[source]#

Render one sound’s TASL attribution line.

A source-supplied attribution_text (if non-empty) is returned verbatim; otherwise the line is synthesized from Title/Author/Source/License, with a (modified) notice and an AI-disclosure segment appended as applicable.

Parameters:

source (Union[CreditEntry, SoundRecord, Candidate, LicenseRecord]) – A CreditEntry, or any credit input (coerced first).
fmt (str) – 'markdown' (hyperlinked list-item body) or 'plain' (text with URLs in parentheses).

Return type:

str

Returns:

The attribution line (no leading bullet / trailing newline).

foley.provenance.credit_entry(record, *, title=None)[source]#

Build a CreditEntry from a record (title override optional).

Every field is read straight off the LicenseRecord (flags never re-derived); modified reflects a non-empty transformations list.

Parameters:

record (Union[SoundRecord, Candidate, LicenseRecord]) – A SoundRecord, Candidate, or LicenseRecord.
title (Optional[str]) – Explicit title override (else resolved from caption/tags/…).

Return type:

CreditEntry

foley.provenance.credits_for(sounds, *, title='Credits', only_required=False, sort='appearance')[source]#

Build the deduplicated Credits for the sounds used in a run.

Parameters:

sounds (Iterable[Union[SoundRecord, Candidate, LicenseRecord]]) – An iterable of records / candidates / license records.
title (str) – The credits heading (also carried in the manifest).
only_required (bool) – Keep only entries whose license requires attribution (drops CC0 / user-owned courtesy credits). Default False credits everything (never-discard-provenance).
sort (str) – 'appearance' (default: first-seen order), 'author', or 'title' (case-insensitive alpha).

Return type:

Credits

Returns:

A Credits; identical sounds (same id) are credited once (first-writer-wins).

foley.provenance.credits_manifest(credits)[source]#

The machine-readable manifest for credits — a JSON-native dict.

entries is a plain list of per-credit dicts (not the tuple that dataclasses.asdict would preserve), so the manifest equals json.loads(credits.to_json()) — the exact shape written to credits.json. It carries the full field set, including the requires_attribution mark and the watermark / c2pa_manifest_ref pass-throughs (None until #9b).

Return type:: dict

foley.provenance.render_credits_md(credits, *, title=None, heading_level=2)[source]#

Render credits as a deterministic CREDITS.md document.

Parameters:

credits (Credits) – The Credits to render.
title (Optional[str]) – Heading override (default: credits.title).
heading_level (int) – Markdown heading level for the title (default 2 → ##).

Return type:

str

Returns:

The Markdown document (bulleted attribution lines; a placeholder note when empty), ending in a single trailing newline.

Modules

`credits`	TASL attribution / credits generator — the provenance render layer (#9a).
`disclosure`	Disclosure, watermarking & safety for AI-generated audio (#9b).