feat(editor): imported audio as a first-class timeline region

.gitignore

@@ -132,3 +132,4 @@ workbench/fixtures/
 /aur_ci
 /aur_ci.pub
 /aur_known_hosts
+tmp_handoff.md

crates/compositor-view-napi/src/lib.rs

@@ -364,6 +364,10 @@ pub struct ClipInput {
     pub webcam_offset_sec: f64,
     /// `false` évite une ouverture ffmpeg vouée à échouer et réserve du silence à ce clip.
     pub has_audio: bool,
+    /// Secondes de sortie pendant lesquelles ce clip TIENT sa dernière image, en silence.
+    /// Une pause achetée par un mot ajouté (issue #560) : le ruler et la preview la
+    /// respectaient déjà, l'export l'ignorait, faute d'une fenêtre source non vide.
+    pub hold_sec: f64,
 }
 
 /// Taille/cadence/codec de sortie voulus par l'app (modale d'export). Tous optionnels :
@@ -500,6 +504,7 @@ pub fn export_multi(
             source_end_sec: c.source_end_sec,
             webcam_offset_sec: c.webcam_offset_sec,
             has_audio: c.has_audio,
+            hold_sec: c.hold_sec,
         })
         .collect();
     Ok(AsyncTask::new(ExportMultiTask {
@@ -657,6 +662,7 @@ pub fn export_gif(
             source_end_sec: c.source_end_sec,
             webcam_offset_sec: c.webcam_offset_sec,
             has_audio: c.has_audio,
+            hold_sec: c.hold_sec,
         })
         .collect();
     let gif_params = params

crates/compositor/src/audio.rs

@@ -5,7 +5,7 @@
 use crate::ffi::*;
 
 use crate::regions::SpeedSegment;
-use crate::scene::SceneAudio;
+use crate::scene::{SceneAudio, SceneAudioTrack};
 use anyhow::{bail, Result};
 use std::f32::consts::PI;
 use std::ffi::CString;
@@ -1381,6 +1381,142 @@ pub fn assemble_concatenated_pcm(
     output
 }
 
+/// Mix imported audio tracks (issue #350) over the assembled programme.
+///
+/// Each track is decoded across its trim window — already resampled to 48 kHz
+/// stereo by `decode_clip_audio`, the same path a clip's own audio takes — scaled
+/// by its per-track gain (the same `10^(dB/20)` law as `finish_audio`), and summed
+/// into the programme at `start_sec`. The programme length is NOT extended: a
+/// track that runs past the video is truncated to it, so the audio and video
+/// streams stay the same length for the muxer.
+///
+/// The decode window is capped up front at the room left in the programme after
+/// `start_sec`, and a track starting at/after the end is skipped without decoding.
+/// `decode_clip_audio` preallocates from the window, so this keeps a long track
+/// pinned near a short programme's end from buffering (and clamping away) hours of
+/// PCM. `trim_end_sec` must therefore be concrete — the renderer sends
+/// `trimEnd ?? durationSec`.
+///
+/// A track whose file has no decodable audio is skipped — the same degradation a
+/// stream-less clip gets.
+pub fn mix_external_tracks(mut programme: PlanarPcm, tracks: &[SceneAudioTrack]) -> PlanarPcm {
+    let programme_len = programme.first().map(Vec::len).unwrap_or(0);
+    if programme_len == 0 {
+        return programme;
+    }
+    for track in tracks {
+        let offset = (track.start_sec.max(0.0) * AUDIO_OUTPUT_SAMPLE_RATE as f64).round() as usize;
+        // A track that starts at or past the programme end contributes nothing —
+        // skip it before decoding anything.
+        if offset >= programme_len {
+            continue;
+        }
+        let trim_start = track.trim_start_sec.max(0.0);
+        let Some(trim_end_full) = track.trim_end_sec else {
+            // Without a concrete end there is no safe window to decode (see the doc
+            // comment); the renderer always resolves one, so this only guards a
+            // hand-written scene.
+            continue;
+        };
+        // Cap the decode window at the room left in the programme. Everything past
+        // `offset` that overflows is discarded by `overlay_track_pcm` anyway, so
+        // decoding it only wastes time and memory — a three-hour track placed at
+        // second 9 of a ten-second export must not buffer three hours of PCM.
+        let remaining_sec = (programme_len - offset) as f64 / AUDIO_OUTPUT_SAMPLE_RATE as f64;
+        let trim_end = trim_end_full.min(trim_start + remaining_sec);
+        if trim_end <= trim_start {
+            continue;
+        }
+        let decoded = match decode_clip_audio(&track.path, trim_start, trim_end) {
+            Ok(Some(pcm)) => pcm,
+            _ => continue,
+        };
+        // The app's own range is -60..+12 dB (the inspector slider); clamping at
+        // -12 here floored every quiet bed at a tenth of the attenuation asked for.
+        let gain = 10.0f32.powf(track.gain_db.clamp(-60.0, 12.0) / 20.0);
+        overlay_track_pcm(
+            &mut programme,
+            &decoded,
+            offset,
+            gain,
+            track.fade_in_sec.max(0.0),
+            track.fade_out_sec.max(0.0),
+        );
+    }
+    programme
+}
+
+/// Sum one decoded track into the programme at `offset` samples, scaled by `gain`,
+/// truncated at the programme's end. Split out of `mix_external_tracks` so the
+/// placement/gain/clamp math is testable without ffmpeg, exactly like
+/// `mix_aligned_tracks` is split from the decode above.
+fn overlay_track_pcm(
+    programme: &mut PlanarPcm,
+    decoded: &PlanarPcm,
+    offset: usize,
+    gain: f32,
+    fade_in_sec: f64,
+    fade_out_sec: f64,
+) {
+    let programme_len = programme.first().map(Vec::len).unwrap_or(0);
+    if offset >= programme_len {
+        return;
+    }
+    let room = programme_len - offset;
+    // The ramps are measured against the DECODED length, not the room left in the
+    // programme: a track running past the end is cut off there, and a fade-out
+    // timed to the cut would ramp down over audio the export never reaches.
+    let decoded_len = decoded.iter().map(Vec::len).max().unwrap_or(0);
+    let (fade_in, fade_out) = resolve_fade_samples(decoded_len, fade_in_sec, fade_out_sec);
+    for channel in 0..AUDIO_OUTPUT_CHANNELS {
+        let Some(source) = decoded.get(channel) else {
+            continue;
+        };
+        let count = source.len().min(room);
+        let dst = &mut programme[channel];
+        for k in 0..count {
+            dst[offset + k] += source[k] * gain * fade_envelope(k, decoded_len, fade_in, fade_out);
+        }
+    }
+}
+
+/// Fade lengths in samples, reduced to fit inside `len`.
+///
+/// Fades that do not fit share the window in proportion rather than being clamped
+/// independently: clamping each to the length first would turn an asymmetric pair
+/// into a symmetric one, losing the shape asked for. Kept identical to the app's
+/// `resolveFadeSecs` so the preview and the render agree.
+fn resolve_fade_samples(len: usize, fade_in_sec: f64, fade_out_sec: f64) -> (usize, usize) {
+    if len == 0 {
+        return (0, 0);
+    }
+    let rate = AUDIO_OUTPUT_SAMPLE_RATE as f64;
+    let mut fade_in = fade_in_sec.max(0.0) * rate;
+    let mut fade_out = fade_out_sec.max(0.0) * rate;
+    let total = fade_in + fade_out;
+    if total > len as f64 && total > 0.0 {
+        let scale = len as f64 / total;
+        fade_in *= scale;
+        fade_out *= scale;
+    }
+    (fade_in.round() as usize, fade_out.round() as usize)
+}
+
+/// Linear ramp factor at sample `k` of a `len`-sample track.
+fn fade_envelope(k: usize, len: usize, fade_in: usize, fade_out: usize) -> f32 {
+    let mut v = 1.0f32;
+    if fade_in > 0 && k < fade_in {
+        v = v.min(k as f32 / fade_in as f32);
+    }
+    if fade_out > 0 && len > k {
+        let remaining = len - k;
+        if remaining <= fade_out {
+            v = v.min(remaining as f32 / fade_out as f32);
+        }
+    }
+    v
+}
+
 /// Encodeur AAC attaché au muxer avant son header. Les paquets utilisent le même interleaver
 /// que la vidéo ; les pts restent en unités échantillon jusqu'au rescale vers l'AVStream.
 pub(crate) struct AacEncoder {
@@ -1493,6 +1629,40 @@ impl Drop for AacEncoder {
     }
 }
 
+#[cfg(test)]
+mod hold_tests {
+    use super::*;
+
+    /// Les images tenues allongent le CRÉNEAU audio du clip sans allonger son PCM, et
+    /// `assemble_concatenated_pcm` laisse des zéros dans ce qui dépasse. Le silence d'une
+    /// pause est donc gratuit : aucun fichier muet à décoder, aucune entrée de mix en plus.
+    #[test]
+    fn a_longer_slot_than_pcm_leaves_silence_at_its_tail() {
+        // 2s de créneau à 1 fps, mais seulement 1s de PCM décodé.
+        let plan = build_audio_concat_plan(&[2], &[true], 1.0);
+        let one_sec = AUDIO_OUTPUT_SAMPLE_RATE as usize;
+        let pcm = vec![Some(vec![vec![0.5f32; one_sec]; AUDIO_OUTPUT_CHANNELS])];
+        let out = assemble_concatenated_pcm(&pcm, &plan);
+        assert_eq!(out[0].len(), 2 * one_sec);
+        assert!((out[0][0] - 0.5).abs() < 1e-6, "le vrai son est bien là");
+        assert_eq!(out[0][2 * one_sec - 1], 0.0, "la queue du créneau est du silence");
+    }
+
+    /// Et le son réel n'est PAS étiré pour remplir le créneau : la voix garde son rythme.
+    #[test]
+    fn the_clips_own_audio_is_not_stretched_to_fill_the_hold() {
+        let plan = build_audio_concat_plan(&[4], &[true], 1.0);
+        let one_sec = AUDIO_OUTPUT_SAMPLE_RATE as usize;
+        let mut source = vec![0.0f32; one_sec];
+        source[0] = 1.0;
+        let pcm = vec![Some(vec![source.clone(), source])];
+        let out = assemble_concatenated_pcm(&pcm, &plan);
+        // L'impulsion reste au premier échantillon, pas répartie sur quatre secondes.
+        assert!((out[0][0] - 1.0).abs() < 1e-6);
+        assert_eq!(out[0][1], 0.0);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1692,6 +1862,68 @@ mod tests {
         assert_eq!(mixed[1], vec![0.25, -0.5, 0.75]);
     }
 
+    // Imported audio track overlay (issue #350).
+    #[test]
+    fn overlay_sums_at_offset_with_gain() {
+        let mut programme = planar(&[0.1, 0.1, 0.1, 0.1]);
+        // ×2 gain, placed at sample offset 1.
+        overlay_track_pcm(&mut programme, &planar(&[0.2, 0.2]), 1, 2.0, 0.0, 0.0);
+        assert_eq!(programme[0], vec![0.1, 0.5, 0.5, 0.1]);
+        assert_eq!(programme[1], vec![0.1, 0.5, 0.5, 0.1]);
+    }
+
+    #[test]
+    fn overlay_truncates_a_track_that_runs_past_the_programme() {
+        let mut programme = planar(&[0.0, 0.0, 0.0]);
+        // A 4-sample track placed at offset 2 has room for only 1 sample.
+        overlay_track_pcm(&mut programme, &planar(&[1.0, 1.0, 1.0, 1.0]), 2, 1.0, 0.0, 0.0);
+        assert_eq!(programme[0], vec![0.0, 0.0, 1.0]);
+    }
+
+    #[test]
+    fn overlay_past_the_end_is_a_no_op() {
+        let mut programme = planar(&[0.3, 0.3]);
+        overlay_track_pcm(&mut programme, &planar(&[1.0]), 5, 1.0, 0.0, 0.0);
+        assert_eq!(programme[0], vec![0.3, 0.3]);
+    }
+
+    #[test]
+    fn mix_external_tracks_skips_empty_windows() {
+        let programme = planar(&[0.4, 0.4]);
+        let tracks = vec![SceneAudioTrack {
+            path: "/nope.mp3".into(),
+            start_sec: 0.0,
+            gain_db: 0.0,
+            trim_start_sec: 2.0,
+            trim_end_sec: Some(1.0), // end <= start: empty window, never decoded
+            fade_in_sec: 0.0,
+            fade_out_sec: 0.0,
+        }];
+        // The empty window is skipped before any decode, so the programme is
+        // untouched even though the path does not exist.
+        let out = mix_external_tracks(programme, &tracks);
+        assert_eq!(out[0], vec![0.4, 0.4]);
+    }
+
+    #[test]
+    fn mix_external_tracks_skips_a_track_that_starts_past_the_programme() {
+        // 2 samples = ~0.00004 s of programme at 48 kHz; the track starts at 1 s, so
+        // its offset is past the end. It must be skipped before any decode is
+        // attempted (the path does not exist), never buffering its window.
+        let programme = planar(&[0.4, 0.4]);
+        let tracks = vec![SceneAudioTrack {
+            path: "/nope.mp3".into(),
+            start_sec: 1.0,
+            gain_db: 0.0,
+            trim_start_sec: 0.0,
+            trim_end_sec: Some(3600.0),
+            fade_in_sec: 0.0,
+            fade_out_sec: 0.0,
+        }];
+        let out = mix_external_tracks(programme, &tracks);
+        assert_eq!(out[0], vec![0.4, 0.4]);
+    }
+
     #[test]
     fn single_track_is_not_clamped() {
         // Promesse de non-régression : une source mono-piste ressort telle quelle, y compris
@@ -1784,6 +2016,73 @@ mod tests {
         assert!((loud[0][0] - ceiling).abs() < 1e-6);
     }
 
+    #[test]
+    fn fades_that_fit_are_left_alone() {
+        let rate = AUDIO_OUTPUT_SAMPLE_RATE as f64;
+        let (fin, fout) = resolve_fade_samples(rate as usize, 0.1, 0.2);
+        assert_eq!(fin, (0.1 * rate).round() as usize);
+        assert_eq!(fout, (0.2 * rate).round() as usize);
+    }
+
+    #[test]
+    fn fades_too_long_for_the_track_share_it_in_proportion() {
+        // 6 s + 4 s of fade on a 2 s track → 1.2 s / 0.8 s, not a clamped 1 s / 1 s.
+        // Mirrors `resolveFadeSecs` on the app side; the two must agree or the
+        // preview and the render shape the same track differently.
+        let rate = AUDIO_OUTPUT_SAMPLE_RATE as f64;
+        let len = (2.0 * rate) as usize;
+        let (fin, fout) = resolve_fade_samples(len, 6.0, 4.0);
+        assert_eq!(fin, (1.2 * rate).round() as usize);
+        assert_eq!(fout, (0.8 * rate).round() as usize);
+        assert!(fin + fout <= len + 1);
+    }
+
+    #[test]
+    fn a_fade_in_longer_than_the_track_still_reaches_full_volume() {
+        // Left unreduced this holds the gain near zero for the whole track — the
+        // layer exports silent.
+        let (fin, fout) = resolve_fade_samples(100, 10.0, 0.0);
+        assert_eq!((fin, fout), (100, 0));
+        assert!((fade_envelope(99, 100, fin, fout) - 0.99).abs() < 1e-3);
+    }
+
+    #[test]
+    fn the_envelope_ramps_at_both_edges_and_holds_between() {
+        assert_eq!(fade_envelope(0, 100, 10, 10), 0.0);
+        assert!((fade_envelope(5, 100, 10, 10) - 0.5).abs() < 1e-6);
+        assert_eq!(fade_envelope(50, 100, 10, 10), 1.0);
+        assert!((fade_envelope(95, 100, 10, 10) - 0.5).abs() < 1e-6);
+    }
+
+    #[test]
+    fn overlay_applies_the_fade_over_the_decoded_length() {
+        // The ramps are measured against the DECODED length, not the room left in
+        // the programme: a fade-out timed to the programme's end would ramp down
+        // over audio the export never reaches.
+        let mut programme = planar(&[0.0, 0.0, 0.0, 0.0]);
+        let decoded = planar(&[1.0, 1.0, 1.0, 1.0]);
+        // A 4-sample fade-in at 48 kHz is far below one sample of real time, so
+        // ask for the whole decoded length in seconds.
+        let four = 4.0 / AUDIO_OUTPUT_SAMPLE_RATE as f64;
+        overlay_track_pcm(&mut programme, &decoded, 0, 1.0, four, 0.0);
+        assert_eq!(programme[0][0], 0.0);
+        assert!(programme[0][1] > 0.0 && programme[0][1] < 1.0);
+        assert!(programme[0][3] > programme[0][1]);
+    }
+
+    #[test]
+    fn a_track_gain_below_the_output_bound_is_honoured() {
+        // The per-track gain range is the inspector's -60..+12, NOT the project
+        // output trim's ±12: clamping here at -12 floored every quiet bed at a
+        // tenth of the attenuation asked for.
+        let mut programme = planar(&[0.0]);
+        let decoded = planar(&[1.0]);
+        let gain = 10.0f32.powf(-40.0 / 20.0);
+        overlay_track_pcm(&mut programme, &decoded, 0, gain, 0.0, 0.0);
+        assert!((programme[0][0] - gain).abs() < 1e-9);
+        assert!(programme[0][0] < 10.0f32.powf(-12.0 / 20.0));
+    }
+
     #[test]
     fn output_is_clipped_to_full_scale_and_keeps_its_length() {
         // The trim can push a hot signal past full scale; the timeline must come back the