Skip to content

🎥 Make videos programmatically with React

docs: prefer float WAV for OTIO audio

Jonny Burger467489b9e03f
diff --git a/packages/docs/docs/export-otio.mdx b/packages/docs/docs/export-otio.mdx
index db01601f4e..713fa2566c 100644
--- a/packages/docs/docs/export-otio.mdx
+++ b/packages/docs/docs/export-otio.mdx
@@ -106,7 +106,13 @@ For every audio-bearing `<Audio>`, `<Video>`, or `<OffthreadVideo>`, determine i
- Bake playback rate, looping, tone frequency, stream selection, channel mapping, panning, and other audio processing. If their interaction or target channel layout is ambiguous, render one combined stem and remove every source clip included in that stem.
- If processed audio overlaps other simple audio, either keep separately baked clips so OTIO mixes them additively, or render one combined stem and remove every source clip included in that stem. Never double the mix.
-Preserve the original source and processing values in clip metadata for auditability, but do not treat metadata as the fidelity mechanism. Prefer PCM WAV for processed audio. Remotion's `--codec=wav` renderer emits 16-bit PCM; a separate media processor may explicitly create 24-bit PCM when the source quality warrants it. Probe every derivative or stem and set its `available_range` from the processed file rather than the compressed source container. Keep the clip's `source_range` duration equal to the intended active interval and fail if the processed file does not cover it. For an unlooped whole-source derivative, shorten the active interval to the decoded media duration or render explicit trailing silence when that is part of the intended interval. For constant-gain derivatives, compare decoded PCM against a unity-gain decode or Remotion-rendered reference on non-silent samples, accounting for resampling and clipping.
+Preserve the original source and processing values in clip metadata for auditability, but do not treat metadata as the fidelity mechanism. Keep unprocessed unity-gain audio in its native localized format.
+
+For processed derivatives and stems, prefer 48 kHz 32-bit IEEE-float WAV (`pcm_f32le`) when a verified encoder path and the target editor support it. Preserve the source channel layout. Process constant-gain derivatives directly from the original source, and keep the processing path floating point through encoding. In the float path, do not normalize, limit, clip, dither, or pass through an integer intermediate. Float preserves headroom and relative precision; it does not undo source clipping or codec artifacts, or make a combined stem separable.
+
+Remotion's `--codec=wav` renderer currently emits 16-bit PCM. Do not convert that output to 32-bit float or 24-bit PCM and claim recovered precision. For stems that require a Remotion render, use a verified end-to-end float processor when available. Otherwise keep the direct Remotion stem and report that it is 16-bit. If float output is unavailable for a derivative that can be processed directly, create 24-bit PCM WAV and report the fallback.
+
+Probe every derivative or stem and set its `available_range` from the processed file rather than the compressed source container. Keep the clip's `source_range` duration equal to the intended active interval and fail if the processed file does not cover it. For an unlooped whole-source derivative, shorten the active interval to the decoded media duration or render explicit trailing silence when that is part of the intended interval. For constant-gain derivatives, compare decoded samples against a unity-gain decode or Remotion-rendered reference on non-silent samples, accounting for resampling and clipping.
Render visual fallbacks with the composition's actual props, dimensions, FPS, and frame range. `--frames=S-E` is inclusive, so the resulting clip duration is `E - S + 1` frames:
@@ -294,7 +300,7 @@ Always tell the user:
1. Where the `.otio` file was written.
2. Which elements became native editable clips.
3. Which elements became processed derivatives, rendered overlays, opaque replacements, or audio stems, and why.
-4. Which media files were downloaded, copied, processed, or rendered beside the timeline.
+4. Which media files were downloaded, copied, processed, or rendered beside the timeline. For processed audio, include its sample rate and sample format, and report any fallback from 32-bit float.
5. Anything the user explicitly chose to omit. If anything else could not be represented, report the export as incomplete instead of successful.
Then give the import steps:
@@ -322,6 +328,7 @@ otioconvert -i timeline.otio -o timeline.xml -O fcp_xml
- Do not leave an HTTP or HTTPS URL in `target_url`, or reference media outside the `.otio` file's directory.
- Do not silently omit visible or audible output because OTIO cannot represent it natively. Bake or render it, or stop with an incomplete export.
- Do not rely on generic OTIO effects or application-specific metadata as the only representation of volume, retiming, transforms, or Remotion effects.
+- Do not convert integer PCM output to float and describe it as preserving precision that was already lost.
- Do not leave a replacement fallback active alongside the native video or audio it already contains.
- Do not claim frame accuracy for a composition whose timing depends on runtime data.
- Do not add tracks without a compositing or overlap reason.