@vosjs/studio-core 0.43.0 → 0.45.0

package/README.md

@@ -27,9 +27,11 @@ RecordingArtifact ──projectFromArtifact──▶ ProjectDoc ──lowerStudi
 
 ## Two documents, one editor
 
-`StudioDoc = ProjectDoc | ProgramAnchorDoc`, discriminated on `source`. A `ProjectDoc` is a recording: footage, `segments` (the kept source spans), `zoom`, `speed`, `tilt`, `camMotion`, the frame and cursor styles, plus the shared layers. A `ProgramAnchorDoc` is a vos program that gained the same shared layers (text, image and video overlays, 3D objects, audio clips, speed spans, a tween-retime overlay) without those being written into its config. `anchorKindOf`, `isRecordingDoc` and `isProgramDoc` read the discriminator; `lowerProgramDoc` lowers the program kind. Hosted documents carry `docSchemaVersion` (`DOC_SCHEMA_VERSION`, currently 2) and are upgraded on read with `migrateHostedDoc`.
+`StudioDoc = ProjectDoc | ProgramAnchorDoc`, discriminated on `source`. A `ProjectDoc` is a recording: footage, `segments` (the kept source spans, played in order; one may repeat seconds an earlier one played, and every source-anchored span over them plays in each occurrence, see `spanOutputExtents`; one marked `camera: 'rest'` keeps the camera at rest through its pass, and a step anchor reads the pass its step plays longest), `zoom`, `speed`, `tilt`, `camMotion`, the frame and cursor styles, plus the shared layers. A `ProgramAnchorDoc` is a vos program that gained the same shared layers (text, image and video overlays, 3D objects, audio clips, speed spans, a tween-retime overlay) without those being written into its config. `anchorKindOf`, `isRecordingDoc` and `isProgramDoc` read the discriminator; `lowerProgramDoc` lowers the program kind. Hosted documents carry `docSchemaVersion` (`DOC_SCHEMA_VERSION`, currently 2) and are upgraded on read with `migrateHostedDoc`.
 
-The shared layers lower as one engine `stack` entry, `STUDIO_ENTRY_ID` (`'vosso.studio'`), with its own data (`studioLayerData`), so either document kind hosts them and the engine's `SET_DATA { target }` updates them alone. `studioAudioPlan` turns the entry's audio clips and duck curve into the plan `@vosjs/core/audio` mixes.
+The shared layers lower as one engine `stack` entry, `STUDIO_ENTRY_ID` (`'vosso.studio'`), with its own data (`studioLayerData`), so either document kind hosts them and the engine's `SET_DATA { target }` updates them alone. `studioAudioPlan` turns the entry's audio clips and duck curve into the plan `@vosjs/core/audio` mixes. An audio clip's `gain` is 0..1; a clip may carry a loudness target instead, `normalize` (integrated LUFS, -30..-6), beside the file's measured `loudness` (`{ lufs, peakDb, at, src }`, written by tooling): `clipGain` derives the gain it plays at, `10^((normalize - lufs) / 20) × gain`, which may exceed 1 and is capped so the sample peak stays under -1 dBFS (and never lifts more than +24 dB). The target applies only while `loudness.src` is the clip's `key`; a clip without one lowers byte for byte as before.
+
+**What a renderer must understand.** `DOC_FEATURES` lists the document fields a host's lowering must read, each with the release that first renders it and a predicate that finds it (`docFeatures(doc)`, `featuresNewerThan(doc, version)`), so a tool that hands a document to a host on an older release can say so before it is sent. `bakeDocFeatures(doc, version)` returns a copy with each newer feature it can bake said in what that release reads: an anchored caption at the start it plays at in this cut, `{elapsed}` filled, a loudness target as its gain (up to 1), with notes for what changed.
 
 ## Time and space conventions