feat(tts): add --tts-pad-silence-ms to circumvent VLC C2PA buffer drop

This introduces `tts_pad_silence_ms` to the TTS pipeline to inject pure
silence frames at the head of the audio before writing to file or
handing back via the ABI.

VLC drops the initial ~1.5 seconds of streaming playback when reading a
file containing a massive C2PA manifest (often 2-3KB appended at the end
of a WAV file). Padding the audio stream directly ensures VLC only drops
the padded silence, preserving the actual spoken speech while leaving the
cryptographic provenance manifest intact.

This is exposed to all ABI integrations via
`crispasr_session_set_tts_pad_silence_ms(session, ms)` and the HTTP API
as `"pad_silence_ms"`. For streaming ABI paths, the padding is only
applied to the first chunk to avoid accumulating inter-sentence latency.

Author: CrispStrobe

bindings/csharp/CrispASR/NativeMethods.cs

@@ -88,6 +88,10 @@ internal static extern int crispasr_session_set_instruct(
         internal static extern int crispasr_session_set_tts_phonemes(
             IntPtr s, [MarshalAs(UnmanagedType.LPUTF8Str)] string phonemes);
 
+        [DllImport(Lib, CallingConvention = CallingConvention.Cdecl)]
+        internal static extern void crispasr_session_set_tts_pad_silence_ms(
+            IntPtr s, int ms);
+
         [DllImport(Lib, CallingConvention = CallingConvention.Cdecl)]
         internal static extern int crispasr_session_is_custom_voice(IntPtr s);
 

bindings/csharp/CrispASR/Session.cs

@@ -177,6 +177,12 @@ public void SetTtsPhonemes(string phonemes)
             if (rc != 0) throw new InvalidOperationException($"set_tts_phonemes failed (rc={rc})");
         }
 
+        /// <summary>Pad N ms of silence at the beginning of TTS output. Useful to bypass VLC playback bugs where it drops the first ~1.5s of audio while parsing a large C2PA chunk.</summary>
+        public void SetTtsPadSilenceMs(int ms)
+        {
+            NativeMethods.crispasr_session_set_tts_pad_silence_ms(Handle, ms);
+        }
+
         /// <summary>Whether the loaded model is a qwen3-tts CustomVoice variant.</summary>
         public bool IsCustomVoice => NativeMethods.crispasr_session_is_custom_voice(Handle) != 0;
 

bindings/go/crispasr_session.go

@@ -83,6 +83,7 @@ int              crispasr_session_n_speakers(CrispasrSession* s);
 const char*      crispasr_session_get_speaker_name(CrispasrSession* s, int i);
 int              crispasr_session_set_instruct(CrispasrSession* s, const char* instruct);
 int              crispasr_session_set_tts_phonemes(CrispasrSession* s, const char* phonemes);
+void             crispasr_session_set_tts_pad_silence_ms(CrispasrSession* s, int ms);
 int              crispasr_session_is_custom_voice(CrispasrSession* s);
 int              crispasr_session_is_voice_design(CrispasrSession* s);
 float*           crispasr_session_synthesize(CrispasrSession* s, const char* text, int* out_n_samples);
@@ -1072,6 +1073,13 @@ func (s *CrispasrSession) SetTTSPhonemes(phonemes string) error {
 	}
 }
 
+// SetTTSPadSilenceMs pads N ms of silence at the beginning of TTS output.
+// Useful to bypass VLC playback bugs where it drops the first ~1.5s of audio
+// while parsing a large C2PA chunk.
+func (s *CrispasrSession) SetTTSPadSilenceMs(ms int) {
+	C.crispasr_session_set_tts_pad_silence_ms(s.handle, C.int(ms))
+}
+
 // IsCustomVoice reports whether the loaded model is a qwen3-tts
 // CustomVoice variant (use SetSpeakerName for it).
 func (s *CrispasrSession) IsCustomVoice() bool {

bindings/java/src/main/java/io/github/ggerganov/whispercpp/CrispasrSession.java

@@ -46,6 +46,7 @@ public interface Lib extends Library {
         int     crispasr_session_set_instruct(Pointer session, String instruct);
         // #316: synthesize these phonemes verbatim, skipping the G2P. Empty clears. kokoro and piper only (rc=-2 otherwise).
         int          crispasr_session_set_tts_phonemes(Pointer session, String phonemes);
+        void         crispasr_session_set_tts_pad_silence_ms(Pointer session, int ms);
         int     crispasr_session_is_custom_voice(Pointer session);
         int     crispasr_session_is_voice_design(Pointer session);
         Pointer crispasr_session_synthesize(Pointer session, String text, IntByReference outNSamples);
@@ -737,6 +738,11 @@ public void setTtsPhonemes(String phonemes) {
         if (rc != 0) throw new RuntimeException("set_tts_phonemes failed (rc=" + rc + ")");
     }
 
+    /** Pad N ms of silence at the beginning of TTS output. Useful to bypass VLC playback bugs where it drops the first ~1.5s of audio while parsing a large C2PA chunk. */
+    public void setTtsPadSilenceMs(int ms) {
+        Lib.INSTANCE.crispasr_session_set_tts_pad_silence_ms(handle, ms);
+    }
+
     /**
      * Whether the loaded model is a qwen3-tts CustomVoice variant
      * (use {@link #setSpeakerName(String)} for it).

bindings/javascript/emscripten.cpp

@@ -45,6 +45,7 @@ const char* crispasr_session_get_speaker_name(CrispasrSession* s, int i);
 int crispasr_session_set_instruct(CrispasrSession* s, const char* instruct);
 // #316: synthesize these phonemes verbatim, skipping the G2P. Empty clears. kokoro and piper only (rc=-2).
 int crispasr_session_set_tts_phonemes(struct crispasr_session* s, const char* phonemes);
+void crispasr_session_set_tts_pad_silence_ms(struct crispasr_session* s, int ms);
 int crispasr_session_is_custom_voice(CrispasrSession* s);
 int crispasr_session_is_voice_design(CrispasrSession* s);
 float* crispasr_session_synthesize(CrispasrSession* s, const char* text, int* out_n_samples);
@@ -642,6 +643,13 @@ EMSCRIPTEN_BINDINGS(whisper) {
                              return crispasr_session_set_tts_phonemes(g_tts_session, phonemes.c_str());
                          }));
 
+    // Pad N ms of silence at the beginning of TTS output. Useful to bypass VLC playback bugs.
+    emscripten::function("ttsSetPadSilenceMs", emscripten::optional_override([](int ms) {
+                             if (!g_tts_session)
+                                 return;
+                             crispasr_session_set_tts_pad_silence_ms(g_tts_session, ms);
+                         }));
+
     // qwen3-tts variant detection (returns false also when the active
     // backend isn't qwen3-tts).
     emscripten::function("ttsIsCustomVoice", emscripten::optional_override([]() -> bool {

bindings/ruby/ext/ruby_crispasr_session.c

@@ -45,6 +45,7 @@ extern const char* crispasr_session_get_speaker_name(struct CrispasrSession* s,
 extern int crispasr_session_set_instruct(struct CrispasrSession* s, const char* instruct);
 /* #316: synthesize these phonemes verbatim, skipping the G2P. Empty clears. kokoro and piper only (rc=-2 otherwise). */
 extern int crispasr_session_set_tts_phonemes(struct CrispasrSession* s, const char* phonemes);
+extern void crispasr_session_set_tts_pad_silence_ms(struct CrispasrSession* s, int ms);
 extern int crispasr_session_is_custom_voice(struct CrispasrSession* s);
 extern int crispasr_session_is_voice_design(struct CrispasrSession* s);
 extern float* crispasr_session_synthesize(struct CrispasrSession* s, const char* text, int* out_n_samples);
@@ -771,6 +772,12 @@ static VALUE rb_session_set_tts_phonemes(VALUE self, VALUE handle, VALUE phoneme
     return Qnil;
 }
 
+static VALUE rb_session_set_tts_pad_silence_ms(VALUE self, VALUE handle, VALUE ms) {
+    struct CrispasrSession* s = (struct CrispasrSession*)NUM2ULL(handle);
+    crispasr_session_set_tts_pad_silence_ms(s, NUM2INT(ms));
+    return Qnil;
+}
+
 static VALUE rb_session_is_custom_voice(VALUE self, VALUE handle) {
     struct CrispasrSession* s = (struct CrispasrSession*)NUM2ULL(handle);
     return crispasr_session_is_custom_voice(s) ? Qtrue : Qfalse;
@@ -1879,6 +1886,7 @@ void init_ruby_crispasr_session(VALUE* mWhisper) {
     rb_define_singleton_method(mSession, "speakers", rb_session_speakers, 1);
     rb_define_singleton_method(mSession, "set_instruct", rb_session_set_instruct, 2);
     rb_define_singleton_method(mSession, "set_tts_phonemes", rb_session_set_tts_phonemes, 2);
+    rb_define_singleton_method(mSession, "set_tts_pad_silence_ms", rb_session_set_tts_pad_silence_ms, 2);
     rb_define_singleton_method(mSession, "is_custom_voice", rb_session_is_custom_voice, 1);
     rb_define_singleton_method(mSession, "is_voice_design", rb_session_is_voice_design, 1);
     rb_define_singleton_method(mSession, "synthesize", rb_session_synthesize, 2);

crispasr-sys/src/lib.rs

@@ -582,6 +582,10 @@ extern "C" {
         s: *mut CrispasrSession,
         phonemes: *const c_char,
     ) -> c_int;
+    pub fn crispasr_session_set_tts_pad_silence_ms(
+        s: *mut CrispasrSession,
+        ms: c_int,
+    );
     // qwen3-tts variant detection (returns 0/1; 0 also covers "not qwen3-tts").
     pub fn crispasr_session_is_custom_voice(s: *mut CrispasrSession) -> c_int;
     pub fn crispasr_session_is_voice_design(s: *mut CrispasrSession) -> c_int;

crispasr/src/lib.rs

@@ -1683,6 +1683,12 @@ impl Session {
         Ok(())
     }
 
+    /// Pad N ms of silence at the beginning of TTS output. Useful to bypass VLC playback bugs
+    /// where it drops the first ~1.5s of audio while parsing a large C2PA chunk.
+    pub fn set_tts_pad_silence_ms(&self, ms: i32) {
+        unsafe { crispasr_sys::crispasr_session_set_tts_pad_silence_ms(self.handle, ms as std::os::raw::c_int) };
+    }
+
     /// Select + load a punctuation-restoration model (`auto`/`firered`/`fullstop`/
     /// `punctuate-all`/`pcs`/path; `"none"`/`""` unloads). Auto-downloads on first use.
     pub fn set_punc_model(&self, punc_model: &str) -> Result<(), String> {

docs/tts.md

@@ -1843,6 +1843,12 @@ Build the library for the target with `-DCRISPASR_C2PA_FETCH=ON`:
      (all modern browsers, 2023+). Only needed for `c2paSign(bytes, "audio/mpeg")`
      and other non-WAV containers in the browser.
 
+**VLC Playback Bug (Silence Padding).** Because the C2PA JUMBF metadata chunk is extremely large (often 2-3 KB), some audio players (notably **VLC**) stall their playback thread for ~1.5 seconds while parsing it from the end of the file before playing the stream. For short TTS clips, this causes the first 1-2 seconds of the generated speech to be silently dropped during playback.
+To work around this while keeping the C2PA metadata intact, you can explicitly pad silence frames at the beginning of the audio. By the time the player unblocks, the silence has played out and the speech begins unharmed.
+- **CLI:** `--tts-pad-silence-ms 1500`
+- **C ABI:** `crispasr_session_set_tts_pad_silence_ms(session, 1500)`
+- **HTTP Server:** Add `"pad_silence_ms": 1500` to the JSON request body.
+
 ### Voice cloning consent gate
 
 Voice cloning (`.wav` reference files) requires explicit consent:

examples/cli/cli.cpp

@@ -730,6 +730,8 @@ static bool whisper_params_parse_arg_streaming_tts(int argc, char** argv, int& i
         params.g2p_dict = ARGV_NEXT;
     } else if (arg == "--tts-trim-silence") {
         params.tts_trim_silence = true;
+    } else if (arg == "--tts-pad-silence-ms") {
+        params.tts_pad_silence_ms = std::stoi(ARGV_NEXT);
     } else if (arg == "--tts-play") {
         params.tts_play = true;
     } else if (arg == "--tts-play-device") {
@@ -1468,6 +1470,9 @@ static void whisper_print_usage(int /*argc*/, char** argv, const whisper_params&
             params.tts_speed);
     fprintf(stderr, "             --tts-trim-silence       [%-7s] trim leading silence from TTS output\n",
             params.tts_trim_silence ? "true" : "false");
+    fprintf(stderr,
+            "             --tts-pad-silence-ms N   [%-7d] prepend N ms of silence (useful for VLC C2PA buffer drop)\n",
+            params.tts_pad_silence_ms);
     fprintf(stderr, "             --tts-play               [%-7s] play synthesised audio on the local speaker\n",
             params.tts_play ? "true" : "false");
     fprintf(stderr, "             --tts-play-device N      [%-7d] speaker device index (-1 = default)\n",