Audio and video nuances

Use media_probe before editing or converting. It reports the actual container, duration, codecs, stream indexes, sample rate, channels, frame rate, rotation, languages, flags and chapters. A filename extension alone is not enough to choose an export.

Audio: Hz, bitrate and containers

Audio-file conversion uses the first audio stream. To export every soundtrack from a video, use extract_audio instead.

audio_analyze measures the first audio track: integrated loudness in LUFS, loudness range in LU, true/sample peaks and RMS in dB, plus silence ranges. Silence detection uses silence_threshold_db and min_silence_seconds; it is not speech recognition. Discover media_edit for two-pass EBU R128 loudness normalization, volume changes and fades.

Video operations and tracks

For a one-off render, media_edit applies ordered operations: trim, crop, scale, rotate, flip, speed, fps, volume, normalize, fade, mute, replace/mix audio, image overlays and text. It writes one new file. Use media_join for 2–50 clips and optional crossfades.

Operation times refer to the timeline after preceding operations. After trimming source 10–20 seconds, timeline zero is source second 10. Speed changes alter subsequent duration and timing. Do not apply source timestamps unchanged to a transformed timeline.

• video_trim defaults to a precise re-encode. precise: false cuts losslessly at keyframes, with potentially imprecise edges. Select it only when the user accepts that tradeoff.
• convert can select audio/subtitle streams or burn one subtitle track. Use stream indexes returned by probing. Inspect dropped-stream details where returned; the target container may not support every original stream.
• In the current implementation, media_edit preserves compatible extra streams for supported video operations. It can refuse trims or speed changes that cannot retime every track or chapter. Use dedicated video_trim for a cut; audio-only edits refuse multi-audio input rather than picking one track. Older tool descriptions may still say subtitle/data tracks are dropped. Probe the result rather than assuming every container can carry every stream.
• media_join fits videos to a common canvas (default first clip size and frame rate), using padding; clips without audio receive silence. Optional joined-audio normalization targets -16 LUFS. Joins keep the highest source audio rate and speaker positions where supported; WAV retains source precision. Unsupported output combinations can be refused.
• Re-encoded legacy containers can become MP4. Do not promise that DVR, raw or surveillance input keeps its original container on export.
• HEVC/AV1 choices depend on the installed encoder/runtime and target compatibility. Check capabilities and the resulting file; hardware availability is not universal.

Current media_edit bounds include four hours and 7680×4320; GIF output is limited to 60 seconds and 1920 pixels wide. These are operation limits, not a promise that every machine can render at the maximum.

Blur and pixelate video regions

Use video_blur to obscure faces, license plates, screens or other manually located regions in a new video copy. First use extract_frames or video_contact_sheet to find positions and check the relevant times.

These are placed regions with time ranges, not automatic face recognition or object tracking. If a subject moves, account for its positions over time and inspect frames across the full affected range. Audio is copied: blurring a face or screen does not remove spoken names or other sensitive sound. Choose a separate audio edit when needed.

Blurring/pixelation is visual obscuring, not a guarantee that sensitive information cannot be inferred. The source file remains unchanged. For selectable PDF text use the PDF redaction workflow rather than treating blur as text removal. For editable ongoing video work, use project masks in a supported video project.

Other media and privacy tools

• video_to_gif: a selected segment up to 60 seconds, 1–30 fps and 100–1920 pixels wide. GIF is an animated image, so it does not carry the video’s audio.
• extract_audio: exports each audio stream as a separate file; use the returned output paths for multilingual or multi-track inputs. WAV/FLAC preserve precision where the encoder can represent it. For first-track mono speech preparation, use captions_audio instead.
• extract_frames: exports frames at chosen times or evenly spaced, as PNG/JPG in a new folder. video_contact_sheet instead creates one labelled tiled overview.
• remove_audio: writes a silent copy by copying remaining streams without re-encoding. Streams the destination container cannot hold are reported in droppedStreams.
• burn_subtitles: permanently renders a supplied SRT/VTT/ASS file into the video, with supported styling options. This differs from keeping a switchable subtitle track.
• strip_metadata: makes copies of images (including EXIF/GPS cleanup), video, audio and PDF. Video retains audio/subtitle tracks and their languages where supported; check droppedStreams. Metadata stripping does not remove sensitive visible content or sound, and retaining track languages is not the same as deleting every descriptive field everywhere.

Picture fidelity and track compatibility

Current source trim, compression, blur and subtitle-burn paths preserve compatible tracks and source picture precision where supported. A codec/container that cannot retain the input may be refused instead of silently reducing picture precision. An MP4 remux is a stream copy, whereas a filter or precise trim may re-encode. For rich subtitle and attachment streams, check whether Matroska is an appropriate target. Review the returned warnings and probe the output for bit depth, track count, language and flags. A preserved pixel format does not mean the picture was encoded losslessly.

Subtitles and speech

For the complete extraction → transcription → validation → caption handoff, read agent-assisted captions and speech.

subtitles_extract writes embedded text subtitles to SRT, VTT or ASS. Picture subtitles such as PGS or DVD subtitles cannot become text through extraction. subtitles_retime uses newTime = time × scale + shift_seconds; cues entirely before zero are dropped and crossing cues start at zero. Burned subtitles become pixels and cannot be switched off like a subtitle track.

For agent-produced captions:

1. captions_audio extracts temporary 16 kHz mono speech audio as MP3 or WAV. This special speech-preparation path differs from general audio conversion.
2. Transcribe using the agent’s own speech-to-text service or model. FileHop supplies no speech model; external transcription may send audio to that provider.
3. captions_write receives SRT/WebVTT text or timed cues, with the returned audio_id. It validates timing and writes a uniquely named sidecar SRT. Temporary audio is released after saving when the ID is supplied; abandoned files become eligible for cleanup after two hours.

Missing audio is reported as no_audio_track. Invalid cues cause refusal rather than a partially written subtitle file. For captions inside an editable video project, use project_video_edit caption edits instead.

Editable video

Use a videoEditor project for work the user will continue adjusting. Its typed edits distinguish timeline seconds, source offsets and audio fade milliseconds. Independent captions, audio and overlay tracks retain absolute times; they do not automatically ripple with clip changes. Locked items refuse edits.

Inspect both project revisions, make typed changes, render a short audiovisual range with project_video_preview, and inspect before export. The bounded preview is at most 15 seconds and 1920 pixels; it is evidence for that range, not the entire movie. See projects.