Waveform Editor

Waveform Editor

The Waveform tab inside the Subtitle Editor is a full editing surface, not just a viewer. It offers a large active-cue bar above the wave, text labels inside every region, visible keyframe and quality markers, and toolbar sliders for amplitude and playback rate.

The actual subtitle file (SRT or ASS) is rewritten only when you press Save in the modal — every drag and shortcut just stages an in-memory edit, so you can experiment freely.

What you see

Hallo Du da? Stop! Hört mich an.

gap / overlap quality markers A B C F G Active cue bar Sticky timeline Cue labels Keyframe markers Quality markers

Opening It

1. Open any cached subtitle from Library → Movie/Episode detail.
2. Click Edit on a sidecar pill — the Subtitle Editor opens.
3. Switch to the Waveform tab. The audio track is extracted on demand (cached per audio stream), so the first open per video may take a few seconds.

If the source video has multiple audio tracks (Japanese / English / commentary), a track picker shows up next to the toolbar — switching re-extracts and renders the chosen track.

Editing a Cue

1. Click a cue in the Cues tab to select it. The selected region highlights on the waveform.
2. Drag the region edges to retime start/end. The drag-end commit snaps to the closest anchor (see below) and enforces a minimum cue duration of 80 ms.
3. Drag the region body to shift both edges by the same delta — useful for nudging a whole line without changing its length.
4. Use the L/R click map for fast set:
   • Left click anywhere on the waveform → sets the selected cue’s start to that time (snapped).
   • Right click → sets the end.

The header pill on the cue turns “edited” once you’ve staged a change; Save writes it back to disk.

Snap Targets

Drag-end and click commits use a three-pool snap algorithm: the closest anchor inside its tolerance wins; ties favour keyframes, then scenes, then neighbouring cues.

Pool	Default tolerance	Source
Keyframes	150 ms	ffprobe -skip_frame nokey against the video
Scene changes	200 ms	PySceneDetect (lazy-imported; install scenedetect to enable)
Neighbouring cue boundaries	80 ms	The currently parsed subtitle file

Scene markers paint as thin amber lines on the waveform. The “N scene cuts” status pill confirms how many were detected; if the host doesn’t have scenedetect installed, the pool stays empty and the algorithm falls back to keyframes + neighbours.

Speech Detection (VAD)

New in 1.10.0. The Speech toggle adds a fourth pool: the intervals where someone is actually talking, detected from the audio itself rather than inferred from the picture.

Enabling it draws a green strip under the wave marking every detected speech segment, and adds speech edges as snap targets — so a cue boundary can latch onto the moment a line starts instead of a nearby keyframe that happens to be close.

This is the most reliable anchor for dialogue timing, because it comes from the same signal the subtitle describes. Scene cuts and keyframes tell you where the picture changes; only the speech lane tells you where the voice does.

Detection runs on the backend the first time you enable it for a file and can take a moment on a long episode. It is off by default and the choice is remembered.

Reading Speed (CPS)

New in 1.10.0. Characters per second is the standard readability measure for subtitles: a line the viewer cannot finish before it disappears is a defect even when its timing is technically correct.

The active-cue bar and the cue list both show the CPS value for each cue. Values in a comfortable range stay muted; the number turns amber as it climbs past what a viewer can follow, so scanning the list surfaces the problem lines without reading a single one of them.

Fixing a CPS problem usually means extending the cue’s end — or splitting it (F) when the line is simply too long for its slot.

Issue Summary and Safe Fixes

New in 1.10.0. The toolbar carries a file-level chip — for example “438 Cues · ⚠ 93 Probleme” — that counts every flagged cue in the file: overlaps, gaps, CPS violations and zero-length cues. It is the fastest way to judge whether a subtitle needs work before you start scrolling.

Fix safe defects applies the unambiguous corrections in one pass: the ones where there is only one sensible answer, such as an overlap between two adjacent cues or a negative duration. It never touches anything requiring judgement — it will not rewrite text, merge lines, or decide how long a cue “should” be.

You get a preview of what would change before anything is applied, and the whole batch reverts as a single undo step, so trying it costs nothing.

Jump Navigation

New in 1.10.0. Rather than dragging along the timeline hunting for the next thing that needs attention, jump straight to it:

Target	Keys
Scene cuts	C / Shift+C (next / previous)
Keyframes	via the Keyframes control
Timing defects	via the issue chip — steps through the flagged cues

Jumping to defects pairs naturally with the issue chip: open the count, step through the problems, fix or accept each one.

Loop Audition

New in 1.10.0. Loop plays the selected cue over and over with a short pre- and post-roll, so you hear the line in context instead of starting exactly on the boundary you are trying to judge. Adjust the boundary while it loops and the change is audible on the next pass.

This is the fastest way to answer “does this cue start too early?” — the pre-roll lets you hear the silence before the line, which is precisely the part a boundary-aligned playback hides.

Keyboard Shortcuts

The editor follows Aegisub’s Medusa-style layout. Press ? at any time to open a shortcut overlay listing every action.

Group	Keys	Action
Playback	Space	Play / pause
Timing	S / D	Set start / end at playhead
Timing	F / G	Split at cursor / merge with next cue
Navigation	← / →	Seek 100 ms back / forward
Navigation	Shift+← / Shift+→	Seek 1 s back / forward
Navigation	↑ / ↓	Select previous / next cue
Navigation	C / Shift+C	Jump to next / previous scene cut
Zoom	+ / -	Zoom in / out (multiplicative)
Help	?	Open this overlay

Shortcuts are intentionally suspended while the help modal is open so the close key never collides with another action.

Toolbar

Control	Purpose
Play/Pause	Toggles playback. Same as Space.
Edit / Locked	Drag-edit on/off. Disabled in read-only mode.
Shortcuts	Opens the shortcut overlay.
Spectrogram	Layers a spectrogram view (BSD-3-Clause WaveSurfer plugin). Persisted in localStorage.
Scrub	Plays a tiny audio window (~30 Hz throttled) while you drag, so you can hear what you’re snapping to.
Keyframes	Toggles thin teal vertical lines at every video keyframe so you can see the snap targets you’re aligning to. Off by default — keyframes are dense (~one per 0.5 s) and clutter the wave. Persisted.
Speech	Toggles the VAD speech lane and adds speech edges as snap targets. Off by default; detection runs once per file. Persisted.
Loop	Loops the selected cue with pre-/post-roll for audition.
Fix safe defects	Applies unambiguous timing corrections after a preview; reverts as one undo step.
Zoom slider (horizontal)	1–50 px/sec. Linear slider; the +/- keys do exponential steps.
Amplitude zoom slider (vertical)	1×–5× scaling of the wave’s barHeight. Crucial for editing quiet dialogue — without it whispers look flat. Persisted.
Playback rate slider	0.5×–2.0× with preservesPitch=true, so slowing dialogue down doesn’t make it sound chipmunk-ish. Aegisub-style audition workflow. Persisted.
Auto-center	Keeps the selected cue in view as you switch cues.
Audio track	Hidden when the video has only one audio stream.

Quality Markers (Gap / Overlap)

Two coloured bars along the bottom 6 px of the wave flag adjacent-cue defects:

• Red bar — Two cues overlap (next.start < prev.end). The bar spans the overlap interval; hover for Overlap: cues N ↔ N+1. Most players render overlapped cues unpredictably; the editor should fix these before save.
• Amber bar — Tight gap (default < 80 ms). Spans the gap; hover for Tight gap (<80 ms): cues N → N+1. Whether you fix or keep depends on the source — fast dialogue often demands tight chaining.

Both layers are always on — they’re the kind of quality signal you want to see permanently. To suppress them in a per-component config, set showGapOverlapMarkers={false} on WaveformEditor (no UI toggle shipped because the bars are intentionally cheap).

ASS Karaoke Display

When the active cue is an ASS karaoke line (\k<cs>, \K<cs>, \kf<cs>, \ko<cs> overrides), the editor paints a thin purple tick per syllable on top of the waveform. This is display-only. Sublarr deliberately does not retime karaoke — that workflow stays in Aegisub.

Limits and Notes

• Read-only fall-back: if your install doesn’t grant write access to the subtitle file, the Waveform tab still loads but the Edit/Locked toggle stays locked.
• Scene detection is best-effort: PySceneDetect is lazy-imported. If it’s missing you’ll just see no scene markers — no warning, no failure. To enable, install the optional dep on the host or rebuild the Docker image with pip install scenedetect.
• Per-track caching: Audio extraction caches per (video_path, mtime, track_index). Switching tracks repeatedly during a session is cheap.

See Also

• Multi-Engine Sync — automated alignment when manual edits aren’t worth it.
• Settings → Sync Engines — global sanity threshold and engine ordering.