3b1b/manim · error · Exception

Adding sound at timestamp < 0

Error message

Adding sound at timestamp < 0

What it means

SceneFileWriter.add_audio_segment overlays a new AudioSegment onto the growing soundtrack at a given timestamp. If the requested time is negative, overlay position would be meaningless, so the writer raises an Exception. This is the plumbing behind scene.add_sound(..., time=...).

Source

Thrown at manimlib/scene/scene_file_writer.py:154

    def create_audio_segment(self) -> None:
        self.audio_segment = AudioSegment.silent()

    def add_audio_segment(
        self,
        new_segment: AudioSegment,
        time: float | None = None,
        gain_to_background: float | None = None
    ) -> None:
        if not self.includes_sound:
            self.includes_sound = True
            self.create_audio_segment()
        segment = self.audio_segment
        curr_end = segment.duration_seconds
        if time is None:
            time = curr_end
        if time < 0:
            raise Exception("Adding sound at timestamp < 0")

        new_end = time + new_segment.duration_seconds
        diff = new_end - curr_end
        if diff > 0:
            segment = segment.append(
                AudioSegment.silent(int(np.ceil(diff * 1000))),
                crossfade=0,
            )
        self.audio_segment = segment.overlay(
            new_segment,
            position=int(1000 * time),
            gain_during_overlay=gain_to_background,
        )

    def add_sound(
        self,
        sound_file: str,
        time: float | None = None,

View on GitHub (pinned to dee01804d4)

Solutions

1. Pass time=None to append the sound at the current end of the audio track
2. Clamp the computed timestamp: max(0, t)
3. Fix the timestamp arithmetic (usually a wrong subtraction order when computing when a sound should start)

Example fix

# before
self.add_sound("chime.wav", time=start - delay)  # start - delay < 0
# after
self.add_sound("chime.wav", time=max(0, start - delay))

t = max(0.0, float(computed_time)) if computed_time is not None else None
self.add_sound("clip.wav", time=t)

try:
    self.add_sound(sound, time=t)
except Exception as e:
    if "timestamp" in str(e):
        self.add_sound(sound, time=None)  # append at end
    else:
        raise

When it happens

Trigger: Calling self.add_sound('clip.mp3', time=-1) or any negative timestamp; computing a timestamp from an animation start time that evaluates negative (e.g. subtracting wrong run_time, or a time_offset variable that went below zero).

Common situations: Synchronizing sounds to animations where the offset is computed as start_time - accumulated_time and underflows; passing a time earlier than the clip start; refactoring code that used seconds vs frames inconsistently.

Related errors

• At least 2 mobjects needed for Union.
• At least 2 mobjects needed for Intersection.
• At least 2 mobjects needed for Exclusion.
• Invalid input sample type
• Mobject cannot contain self

AI-assisted analysis of 3b1b/manim@dee01804d4 (2026-08-14). Data as JSON: /api/errors/ab9e99db8181c91f. Report an issue: GitHub.