Skip to content

Latest commit

 

History

History
310 lines (253 loc) · 14.5 KB

projects.md

File metadata and controls

310 lines (253 loc) · 14.5 KB

Portable projects and sample-accurate timelines

denoize project v1 is a local, portable contract for assembling exact regions from one or more audio files. Regions address decoded presentation frames, not container packets or codec delay. Every source and referenced artifact is bound by byte length and SHA-256, and every path in a manifest is a portable locator below one canonical project root.

The supported edit graph is deliberately linear and deterministic. A timeline contains an ordered list of source-bound selections with an explicit channel map, silence padding, and an optional linear crossfade from the immediately preceding selection. Arbitrary overlaps, branches, resampling, future fields, and changed source bytes fail before an output is published. Source and timeline timebases are limited to 1..=768,000 Hz, with 1..=64 channels, matching the bounded streaming decoder and encoder contract.

Project v2 is the additive durable graph used when a linear selection list is not sufficient. V1 remains supported and is the simplest streaming assembler; v2 adds arbitrary clip placement and overlap, nested graphs, tracks and buses, immutable effect revisions, exact automation, repair masks, a hash-chained edit journal, complete render-cache identities, loss-reporting interchange, and detached signed edit provenance.

Project v2 graph and renderer

A v2 manifest is a closed execution contract rather than serialized editor UI state. All IDs are stable and sorted canonically. Time uses explicit integer value/rate clocks and numeric effect values are reduced rationals, so timeline conversion does not depend on locale or a JSON floating-point round trip. The initial root is revision 1 with no parent; every later root must name its parent digest. Each immutable effect history starts at revision 1 and remains contiguous, so a missing historical revision cannot be mistaken for a complete undo/redo chain. Sources, model packages, and their public keys have relative locators plus byte length and SHA-256. Clip and bus nesting cycles, unknown fields, invalid ranges, duplicate IDs, stale effect digests, changed source bytes, traversal-like locators, and resource-limit violations fail closed.

Migrate an existing v1 project, inspect or validate it, then render any graph:

denoize project v2 migrate project-v1.json project-v2.json --root . --pretty
denoize project v2 inspect project-v2.json --pretty
denoize project v2 validate project-v2.json --root . --pretty
denoize project v2 render project-v2.json mix.wav \
  --root . --graph main --jobs 4 \
  --max-memory-mib 1024 --max-output-frames 1382400000 --pretty

inspect parses only the closed document. validate --root additionally rehashes and decodes every source, authenticates every model package against its separately fingerprinted Minisign public key, checks the signed package identity and license component, and reports explicit verified-artifact counts. The renderer resolves all references below one canonical root, checks current fingerprints, resamples source clips to the graph rate, and mixes clips, tracks, nested buses, and nested graphs in stable ID order with scalar f64 accumulation. --jobs is part of the runtime/cache identity, but it does not change the summation order. Publication uses the normal extension-selected WAV, FLAC, Ogg Opus, MP3, or M4A encoder and is atomic; an existing destination is preserved unless --force is given.

The executable v2 baseline supports gain-v1, polarity-v1, and repair-mask-v1, including step or linear gain automation. A denoise-recipe-v1 node is preserved and authenticated in the graph, cache, and provenance contracts, but this renderer rejects it explicitly: it must be executed by the existing independently verified execution-plan renderer. This keeps provisional DSP behavior from being inferred from free-form project metadata.

Journal, undo/redo, checkpoints, and cache

The Rust API exposes hash-linked commands for clip insert/remove/move/split/join, effect-chain replacement, immutable effect-revision append, and explicit revision selection. Undo and redo append the typed inverse command; they never erase history, delete external sources, or replace an already published export. The bounded NDJSON reader accepts only a truncated final record as recoverable and rejects corruption inside the complete prefix. A checkpoint binds the prior root, journal-prefix digest, exact snapshot, and number of compacted entries. The mutation API is single-writer: callers must serialize append/checkpoint operations for a project. Atomic replacement protects each individual write, but it is not a multi-process lost-update lock. The CLI currently exposes read-only journal inspection:

denoize project v2 journal inspect edits.ndjson --pretty

Render-cache keys bind the manifest and graph digests, every source/effect/model fingerprint, graph revision, denoize version, deterministic backend, job count, floating-point contract, output geometry/format/bitrate, metadata policy, and optional provenance-policy digest:

denoize project v2 cache key project-v2.json --graph main \
  --format flac24 --jobs 4 --pretty

A library cache hit is accepted only after reconstructing that request from the current manifest, rehashing all current sources, model packages, and model public keys, authenticating each model package signature and identity, rehashing the candidate output bytes, decoding it under limits, and matching its decoded PCM digest. For a lossy output, the record therefore stores the PCM digest of the decoded cached file, not the pre-encode render buffer.

Cache records are integrity records, not signatures. Acceptance assumes the record and output came from a trusted local cache namespace; v0.85.0 does not claim safe consumption of an attacker-controlled distributed cache that can replace both together. Such a cache needs an independent signed render receipt or an expected output digest from another trust channel.

Interchange and signed edit provenance

Interchange is deliberately loss-reporting and non-executable:

denoize project v2 interchange assess project-v2.json \
  --graph main --format otio --direction export --pretty
denoize project v2 otio export project-v2.json timeline.otio \
  --root . --graph main --accept-losses --pretty
denoize project v2 otio inspect timeline.otio --pretty

Plain .otio export carries editorial structure and namespaced denoize metadata, while every unsupported bus, nested-graph, transition, arbitrary placement, executable effect, automation, repair-mask, model, embedded-media, or provenance semantic is reported. Inspection is read-only and never imports free-form effects. In v0.85.0, .otioz, .otiod, and ADM/BW64 have assessment contracts only; bundle authoring and ADM object/bed authoring are not claimed.

Create and independently verify a detached Ed25519 assertion after rendering:

denoize receipts keygen provenance-secret.json provenance-public.json
denoize project v2 provenance sign project-v2.json mix.wav mix.provenance.json \
  --root . --secret-key provenance-secret.json --format wav-f32 --pretty
denoize project v2 provenance verify mix.provenance.json mix.wav \
  --public-key provenance-public.json --pretty

Signing rehashes every referenced source, model package, and separately fingerprinted model public key, authenticates each model signature and identity, then rehashes the published output bytes and decoded PCM. The payload binds the manifest, selected graph, and the complete nested-graph edit closure. Every clip/effect/mask action names its owner graph and projects its affected range onto one root graph clock, so repeated nested instances cannot be confused with a top-level node that happens to reuse an ID. It also binds immutable operation digests, model identities, output format, and a required signer-disclosure flag. Verification checks the signature, declared container/PCM format, exact bytes, and decoded PCM. The assertion uses a C2PA 2.4 target and c2pa.edited action vocabulary, but v0.85.0 does not embed or claim a complete C2PA manifest store/credential. All formats use a detached handoff in this release; Ogg Opus receives an explicit detached carrier label.

Project v1: create and assemble

The following example selects two stereo intervals on the same 48 kHz presentation timeline. CHANNEL_MAP is a +-separated list of zero-based source channels. Seconds are quantized exactly once to the source timescale.

denoize project create project.json \
  --root . \
  --project-id interview-edit \
  --source main=recording.wav \
  --selection intro=main,12.5,8.0,0+1 \
  --selection answer=main,45.0,20.0,0+1,0,0,0.25 \
  --pretty

# Parse the closed document without opening its references.
denoize project inspect project.json --pretty

# Rehash and fully inspect every source, setting, preset, model, plan, receipt,
# and license reference without changing the project.
denoize project validate project.json --root . --pretty

# Assemble a 32-bit floating-point WAV with bounded block retention.
denoize project assemble project.json assembled.wav \
  --root . --timeline main --pretty

--source-license SOURCE=ID=PATH, --setting ID=PATH, --preset ID=PATH, --model ID=PACKAGE.dmp,PUBLIC_KEY, --plan ID=PATH, and --receipt ID=PATH add authenticated portable references. Settings must parse as TOML, presets use the portable DAW contract, and model packages must pass their existing signature, identity, license, and runtime validation.

Assembly verifies the complete manifest and its references before opening an atomic output transaction. It streams 8,192-frame source blocks and retains only the next adjacent crossfade tail. The published render report binds the manifest, timeline, output bytes, exact presentation geometry, and retained-PCM upper bound. Existing outputs are protected unless --force is explicit.

Plans and signed receipts

A project execution plan records the exact manifest/timeline digests, output locator and publication mode, audio geometry, and conservative memory and temporary-storage bounds:

denoize project plan create project.json assembled.wav \
  --root . --output assembly-plan.json --pretty

denoize receipts keygen receipt-secret.json receipt-public.json
denoize project assemble project.json assembled.wav \
  --root . --plan assembly-plan.json \
  --receipt assembly-receipt.json --receipt-key receipt-secret.json

denoize project receipt verify assembly-receipt.json \
  --root . --public-key receipt-public.json \
  --plan assembly-plan.json --pretty

When --plan is supplied, denoize independently reconstructs the current plan and requires exact equality before assembly. A receipt is signed only for the verified published output and uses a project-specific Ed25519 signature domain. Verification requires either an independently distributed public key or a receipt trust policy, optionally binds the exact plan, and rehashes the rooted output.

Missing-source relocation

Relocation changes only one portable locator. The replacement candidate must remain below the project root and exactly match the recorded byte fingerprint, sample rate, channel count, and presentation frame count:

denoize project relocate project.json main recovered/recording.wav \
  --root . --output relocated-project.json --pretty

The original manifest is never modified by this command. A non-matching candidate publishes no relocated manifest.

Offline bundles

A .dpb bundle always carries the manifest, validation evidence, settings, presets, plans, receipts, source licenses, model public keys, and their exact fingerprints. Source audio and signed model-package payloads remain references by default:

denoize project bundle create project.json project.dpb --root . --pretty
denoize project bundle inspect project.dpb --pretty
denoize project bundle import project.dpb imported-project --pretty

Optional payloads require both an explicit include flag and a positive aggregate byte ceiling:

denoize project bundle create project.json self-contained.dpb \
  --root . \
  --include-sources --max-source-bytes 1073741824 \
  --include-models --max-model-bytes 536870912

Inspection authenticates every length-delimited entry and parses every embedded contract without changing project state. Import stages the complete verified tree beside its destination and publishes only to a new directory. A references-only import reports omitted source and model IDs; the locators stay available for exact-fingerprint recovery.

Batch, watch, and Desktop

Batch preflights every project, destination, and collision before invoking the same assembler. Outputs are sorted by portable locator and published independently:

denoize project batch one.json two.json \
  --root . --output-dir renders --timeline main --pretty

Project watch accepts settled .json manifests below an inbox, assembles each one sequentially, and writes a signed project receipt beside every successful WAV. It uses the durable settle/retry/quarantine engine shared with ordinary watch-folder processing:

denoize project watch inbox renders \
  --root . --receipt-key receipt-secret.json \
  --recursive --once --pretty

The unencrypted receipt key must be outside the inbox and output trees and must remain unchanged for the watcher lifetime. Existing output/receipt collisions are preserved as failures, not overwritten.

The Desktop Project page uses the same Rust contracts. It can load and validate a manifest, select a timeline, preview or save the exact plan, assemble with an optional signed receipt, and create, inspect, or import offline bundles. Source/model inclusion remains opt-in and requires positive MiB limits. Project operations are serialized, and Desktop publication is no-clobber.

Contract and safety summary

All twenty-three project schemas are listed in stable JSON contracts. Project documents are bounded regular non-symlink JSON files, reject unknown fields and future schema versions, and keep integer time/frame values within the exact JSON-safe range. Manifest locators and every referenced artifact are contained below the canonical project root. Plan/receipt, batch, watch, and Desktop paths, imported directories, and bundle entries receive their additional rooted containment checks. An output may not collide with the manifest or any referenced project artifact.

No command modifies source audio. Validation, inspection, and planning are read-only. Creation, relocation, plan/receipt writes, assembly, and bundle creation stage bytes before atomic commit; bundle import uses a staged sibling directory and no-clobber rename.