suno_core/
ffmpeg.rs

1//! The ffmpeg port: transcode WAV bytes to FLAC bytes, and MP4 video previews
2//! to animated WebP cover bytes.
3//!
4//! The lossless download path renders a clip to WAV, then re-encodes it to
5//! FLAC. The animated-cover path fetches a clip's MP4 preview and re-encodes it
6//! to a small looping WebP. Both are the engine's only calls into ffmpeg, so
7//! they sit behind this trait: the CLI adapter wraps a child process (with a
8//! hard timeout), while tests use a stub that returns canned bytes. The steps
9//! only re-encode media; tagging is the pure tagger's job.
10
11use std::future::Future;
12
13use crate::config::AudioFormat;
14
15/// Why an ffmpeg transcode failed, so the executor can treat a full scratch
16/// disk as a systemic abort rather than a skippable per-clip fault.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum FfmpegErrorKind {
19    /// The scratch device or quota ran out of space.
20    OutOfSpace,
21    /// Any other failure (bad input, missing binary, encode error).
22    Other,
23}
24
25/// An ffmpeg transcode failure, carrying a kind and a human-readable,
26/// secret-free reason.
27#[derive(Debug, thiserror::Error)]
28#[error("{reason}")]
29pub struct FfmpegError {
30    kind: FfmpegErrorKind,
31    reason: String,
32}
33
34impl FfmpegError {
35    /// Build an [`FfmpegError`] of kind [`FfmpegErrorKind::Other`] from any
36    /// displayable cause.
37    pub fn new(reason: impl Into<String>) -> Self {
38        Self {
39            kind: FfmpegErrorKind::Other,
40            reason: reason.into(),
41        }
42    }
43
44    /// Build an out-of-space [`FfmpegError`] (kind [`FfmpegErrorKind::OutOfSpace`]).
45    pub fn out_of_space(reason: impl Into<String>) -> Self {
46        Self {
47            kind: FfmpegErrorKind::OutOfSpace,
48            reason: reason.into(),
49        }
50    }
51
52    /// The failure kind.
53    pub fn kind(&self) -> FfmpegErrorKind {
54        self.kind
55    }
56
57    /// Whether this failure was a full scratch disk or exhausted quota.
58    pub fn is_out_of_space(&self) -> bool {
59        self.kind == FfmpegErrorKind::OutOfSpace
60    }
61}
62
63/// Encoder settings for the animated WebP cover derived from a clip's MP4
64/// preview.
65///
66/// The animated WebP is embedded as the audio file's front-cover picture. A
67/// FLAC PICTURE block is length-prefixed with a 24-bit field, so a single
68/// picture cannot exceed ~16 MiB; a real 5 s Suno cover at quality 95 with no
69/// width cap is ~31 MiB and would never fit. The [`Default`] is therefore a
70/// bounded lossy profile that reliably fits that ceiling: quality 90 at effort
71/// (`compression_level`) 4, scaled to at most 640 px wide (owner measurement:
72/// ~11 MiB, ~30% headroom under the cap; 800 px is ~14.5 MiB with far thinner
73/// margin). Effort is capped at 4 because effort 6 only matches its size for
74/// 7-13x the encode time. Lossless is opt-in and far larger (a 5 s cover is
75/// ~145 MB), so it fits only the larger MP3/ALAC containers, never FLAC.
76#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77pub struct WebpEncodeSettings {
78    /// Lossy encoder quality, 0-100 (higher is better and larger). Ignored when
79    /// `lossless` is set.
80    pub quality: u8,
81    /// Cap on the output frame rate; a faster source is downsampled to this.
82    pub max_fps: u32,
83    /// Optional cap on the output width in pixels: `Some(w)` scales a wider
84    /// source down keeping its aspect ratio (never upscaling), while `None`
85    /// keeps the source resolution.
86    pub max_width: Option<u32>,
87    /// Encode losslessly. Off by default: lossless animated WebP of real video
88    /// is intrinsically huge (roughly 30x the lossy source) with no visible
89    /// gain over quality 95 for a cover.
90    pub lossless: bool,
91    /// Encoder effort, 0-4 (higher is smaller and slower). Capped at 4 because
92    /// effort 6 yields the same size for many times the encode time.
93    pub compression_level: u8,
94}
95
96impl Default for WebpEncodeSettings {
97    fn default() -> Self {
98        Self {
99            quality: 90,
100            max_fps: 24,
101            max_width: Some(640),
102            lossless: false,
103            compression_level: 4,
104        }
105    }
106}
107
108/// The ffmpeg port the executor transcodes through.
109///
110/// Async so the adapter can offload the blocking child process without stalling
111/// the runtime; tests resolve immediately.
112pub trait Ffmpeg {
113    /// Transcode `wav` to the given lossless `format`'s bytes.
114    fn wav_to_lossless(
115        &self,
116        wav: &[u8],
117        format: AudioFormat,
118    ) -> impl Future<Output = Result<Vec<u8>, FfmpegError>> + Send;
119
120    /// Transcode an MP4 video preview to animated WebP bytes under `settings`.
121    ///
122    /// Used to derive a clip's `cover.webp` sidecar from its `video_cover_url`
123    /// MP4. Like [`wav_to_lossless`](Ffmpeg::wav_to_lossless) the adapter offloads
124    /// the blocking child process; tests resolve immediately.
125    fn mp4_to_webp(
126        &self,
127        mp4: &[u8],
128        settings: WebpEncodeSettings,
129    ) -> impl Future<Output = Result<Vec<u8>, FfmpegError>> + Send;
130}
suno_core/ffmpeg.rs

suno_core/
ffmpeg.rs
