---
title: Audio and video nuances
description: Audio sample rates, bitrate, containers, timeline timing, subtitle tracks and agent captions.
order: 3
---

# 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

| Concern | FileHop behavior | What an agent should do |
| --- | --- | --- |
| Units | `sample_rate` is samples per second (Hz); `bitrate` such as `192k` is encoded bits per second | Send `48000`, not `48`, for 48 kHz. Do not treat bitrate as sample rate |
| Default rate | Audio conversion uses the source rate when known, with 44100 Hz as a fallback. The target codec can impose its own constraints | Omit the rate to keep the source rate where supported; probe a 96 kHz deliverable to confirm it |
| Explicit rate | The current engine accepts a positive integer in Hz up to 768000; actual supported rates depend on the encoder | Set the rate only for an intentional resample. Some installed tool descriptions still mention only 44100/48000 |
| Opus | FileHop writes 48000 Hz and warns if this differs from the selected/source rate | Inspect warnings; choose another format when 44.1 kHz output is required |
| Lossy targets | MP3, AAC/M4A, OGG and Opus use bitrate controls; conversion defaults to 192k | Raising bitrate cannot recover details already lost |
| MP3 bitrate | MP3 encoding uses constant bitrate for predictable requested bitrate behavior | Container overhead still means file size is not an exact multiplication |
| Lossless targets | WAV/AIFF can keep higher-depth integer and floating-point PCM. FLAC/ALAC refuse supported lossless sources whose precision they cannot carry, such as float PCM | Choose WAV/AIFF when needed. Lossy bitrate settings do not govern these outputs; intentional resampling still changes samples |
| Extension | MCP audio conversion writes AAC or ALAC in M4A. An audio workflow that explicitly preserves an ADTS `.aac` container is a separate choice | Use the returned path; do not rename to raw `.aac` based on the target label |
| Cover art | Conversion copies attached art when the chosen format supports it; otherwise it warns and leaves the original art intact | Check `warnings` and the output if album art is part of the deliverable |
| Compression | Lossy inputs can keep their format; lossless audio compression may produce MP3 | Choose explicit lossless conversion when fidelity is the requirement |

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.

| Option | Behavior |
| --- | --- |
| `regions` | 1–50 regions, applied in order |
| `x`, `y`, `width`, `height` | Percentages of frame dimensions, 0–100; these are not pixels |
| `start`, `end` | Strings in seconds, MM:SS or HH:MM:SS; defaults cover the whole video; end must be after start |
| `effect` | `gaussian` (default), `box`, or `pixelate` |
| `strength` | 0–100, default 50; appearance scales with frame size |
| `shape` | `rectangle` (default), `rounded`, or `ellipse` |
| `softness` | Edge softness 0–100; default 0 is a hard edge |
| `invert` | Blur everything **outside** the selected region instead |

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](/docs/pdf-documents/) 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](/docs/captions/).

`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](/docs/images-projects-archives/).