Vided

Vided is a small local command-line tool for making screen recordings shorter and safer to share.

It trims dead air, speeds up longer pauses, and lets you blur fixed rectangular areas like emails, account IDs, tokens, URL bars, sidebars, or terminal panes. It runs locally with ffmpeg; your video does not leave your machine.

Vided is intended to be used as a CLI tool with uvx or uv tool, not as a Python library dependency.

Example

This is the 90-second public-domain NASA fixture in this repo. VAD trim keeps speech at normal speed and removes or speeds up the gaps, producing a 61.1-second output.

Input, 90.0s

https://github.com/user-attachments/assets/24b476e4-72d3-4bad-843a-3c801cc3adcb

VAD trim, 61.1s

https://github.com/user-attachments/assets/c0ccba07-e2be-45b0-a6a9-d4a7d57f3f28

That output has no blur redactions, so it can be generated with the automatic trim workflow:

uvx vided init tests/fixtures/media/realistic-speech-gaps.mp4 --output-dir realistic-speech-gaps-vad --symlink --overwrite
uvx vided trim realistic-speech-gaps-vad --detector vad --overwrite
uvx vided render realistic-speech-gaps-vad --overwrite

The final clip is written to realistic-speech-gaps-vad/output/final.mp4.

Run as a Tool

Requirements:

• uv
• ffmpeg
• ffprobe
• Python 3.11 or newer, provided by uv or your system

Run Vided with uvx for one-off CLI use. uvx is the short form of uv tool run:

uvx vided --help

For frequent use, install the command persistently:

uv tool install vided
vided --help

The examples below use uvx vided ... so they work without a project-local install.

Workflow

Optional: install the packaged coding-agent skill:

uvx vided install-skill --agent codex
uvx vided install-skill --agent claude

Create a project:

uvx vided init /path/to/recording.mp4 --output-dir my-video

Trim silence:

uvx vided trim my-video --detector vad --overwrite

Use VAD for speech-heavy videos like narration, interviews, demos, and lectures. Use the default audio-level detector when non-speech audio matters, such as music, game audio, room sound, or sound effects.

For redaction, open the local browser UI:

uvx vided ui my-video

In the UI:

1. Click a thumbnail where the redaction starts.
2. Click Set start.
3. Draw the rectangle to blur.
4. Click a thumbnail where it ends.
5. Click Add redaction.

Render a contact sheet preview to review redaction placement without rendering the full final video. Preview sheets sample the trimmed video and show each redaction as a translucent outlined blur region:

uvx vided contact-sheet my-video --overwrite

Render the final blurred video. By default, Vided copies when no video work is needed; otherwise it renders from work/trimmed.mp4:

uvx vided render my-video --overwrite

For smaller screen recordings, make smart compression part of the final render:

uvx vided render my-video --compress smart --overwrite

Optional: render a contact sheet from the final video:

uvx vided contact-sheet my-video --source final --overwrite

Common Tasks

Trim with the default audio-level detector:

uvx vided trim my-video --overwrite

This keeps any sufficiently loud audio activity, including non-speech sound.

Trim with speech-aware VAD:

uvx vided trim my-video --detector vad --overwrite

This is best when the important content is mostly spoken words.

Preview an audio preset on the longest detected speech/sound segment:

uvx vided audio-preview my-video --audio-preset voice-safe --overwrite

Render with an audio preset:

uvx vided render my-video --audio-preset voice-safe --overwrite

Render a smaller screen-recording output with smart compression:

uvx vided render my-video --compress smart --overwrite

Smart compression preserves native resolution for readable UI text, caps high frame-rate recordings to 30fps by default, keeps H.264 for compatibility, and uses source-aware audio bitrate settings so audio is not made larger. It samples candidate encodes automatically before committing to the full render.

uvx vided render my-video --compress smart --compression-priority size --overwrite

Use --compression-priority size when smaller modern-playback files are more important than H.264 compatibility. Smart compressed outputs are guarded by default: if the encoded file would be larger than the source artifact it was rendered from, Vided removes it and reports the size comparison. Use --allow-larger only when you intentionally want a larger quality-focused output.

Render a contact sheet preview:

uvx vided contact-sheet my-video --overwrite

Advanced Flags

Render from the original input and trim timeline instead of work/trimmed.mp4. This is useful when work/trimmed.mp4 was encoded as a small review artifact but the final output should be based on the original source:

uvx vided render my-video --render-source original --compress smart --overwrite

If you only need automatic trimming and want trim to write output/final.mp4 directly, use --final:

uvx vided trim my-video --detector vad --final --overwrite

Use a smaller trim artifact for review:

uvx vided trim my-video --detector vad --compress smart --overwrite

Use --max-fps 24 when a smaller review artifact matters more than motion smoothness.

Smart Compression

--compress smart is the recommended compression workflow for screen recordings. It keeps the original resolution by default because downscaling is the fastest way to make UI text fuzzy. You normally do not need --sample-duration with smart compression because smart mode samples candidates automatically.

H.264 is the default for compatibility. Use --compression-priority size when a smaller file matters more than broad playback support; this allows modern-codec candidates such as H.265. Use --max-fps only when you want to override the default 30fps cap.

Audio Presets

Audio presets are opt-in. By default, Vided copies audio without filtering.

none        copy audio unchanged
level       normalize speech to a conservative -18 LUFS target
voice-safe  gentle voice cleanup plus the same conservative loudness target

List the current presets:

uvx vided audio-presets

Choose your own preview snippet:

uvx vided audio-preview my-video --audio-preset level --start 60 --duration 15 --overwrite

More Examples

These examples use tests/fixtures/media/realistic-speech-gaps.mp4. The none audio preset preview is omitted because it is unchanged audio.

Regenerate them locally:

scripts/generate_example_media.sh

Regenerate and upload release assets:

scripts/generate_example_media.sh --upload

Release assets are stored at https://github.com/pmbaumgartner/vided/releases/tag/examples.

Audio detector trim, 83.1s

https://github.com/user-attachments/assets/b3fa0e0c-a767-4ca6-a7eb-49278230bea1

Audio preset preview: level, 12.5s

https://github.com/user-attachments/assets/965bb188-f499-4c42-924c-1755b85d1a81

Audio preset preview: voice-safe, 12.5s

https://github.com/user-attachments/assets/388c075f-d94b-4cf2-bab8-cff070fc38b1

How Trim Works

The default trim mode is hybrid:

• short silent sections are cut
• silent sections 1.5 seconds or longer are sped up 8x and muted
• speech/sound stays at normal speed
• default margin is 0.2 seconds

The default detector uses ffmpeg-decoded audio levels. It preserves sufficiently loud non-speech sounds like music, game audio, room sound, and sound effects. Use VAD when the video is mostly speech and you want speech-aware trimming:

uvx vided trim my-video --detector vad --overwrite

Trimmed outputs contain only rendered video and audio streams. Subtitle streams, data streams, and chapters are omitted so they cannot extend the reported duration.

Project Files

Vided is file-based. A project keeps the original input, trim output, generated frames, redaction data, and rendered outputs together:

my-video/
  project.json
  redactions.json
  input/original.mp4
  work/trimmed.mp4
  work/frames/
  output/contact-sheet-preview.jpg
  output/final.mp4
  output/contact-sheet.jpg

With VAD, Vided also writes work/vad.wav and work/vad_ranges.json.

Redactions are created against the trimmed video, so redaction timestamps match contact sheet previews and final renders.

Commands

Use command help for details:

uvx vided --help
uvx vided init --help
uvx vided trim --help
uvx vided ui --help
uvx vided contact-sheet --help
uvx vided render --help
uvx vided audio-preview --help

Main commands:

init            create a one-video project
trim            remove or speed up silence
ui              open the local redaction UI
contact-sheet   render a preview or final contact sheet
render          render final video output
audio-presets   list audio presets
audio-preview   render a short audio preset preview
doctor          check ffmpeg/ffprobe availability
install-skill   install the packaged coding-agent skill

When diagnosing local setup or ffmpeg problems, run:

uvx vided doctor

Limitations

• Rectangles are fixed. There is no object tracking.
• Changing trim settings after redacting means regenerating thumbnails and reviewing redactions.
• The UI uses frame thumbnails plus contact sheet previews. It is not a full video editor.
• Frame times follow the thumbnail interval, so this is not for frame-perfect cuts.
• Rotation metadata and unusual pixel aspect ratios are not normalized.
• The local UI server binds to 127.0.0.1 by default. Do not expose it publicly.

Development

From a repo checkout, use uv run for contributor workflows:

uv sync
uv run vided doctor

Run tests:

uv run pytest

Format, lint, and type-check:

uv run ruff format src tests
uv run ruff check src tests
uv run ty check src tests

Install and run pre-commit hooks:

uv run prek install
uv run prek run --stage pre-commit

Run fixture e2e tests:

uv run pytest --run-e2e -m e2e

Install the Playwright browser before browser e2e tests:

uv run playwright install chromium
uv run pytest --run-e2e -m browser --browser chromium

The repo includes two Git LFS-tracked public-domain NASA fixtures:

• tests/fixtures/media/realistic-speech-gaps.mp4
• tests/fixtures/media/realistic-speech-gaps-short.mp4

Source and license notes live beside each fixture as *.LICENSE.md.

Release Notes

Every commit with package source or release metadata changes must bump the package version with zerover. Tests, workflows, docs, scripts, dev dependencies, and uv.lock-only changes do not require a bump.

uv version --bump patch
git add pyproject.toml uv.lock

After committing, add the matching tag:

version="$(uv version --short)"
git tag -a "v$version" -m "v$version"
git push origin HEAD --tags

Publishing runs from .github/workflows/publish.yml when a v* tag is pushed.