Metadata-Version: 2.4
Name: vided
Version: 0.1.20
Summary: A local CLI for speeding up silence and adding rectangular blur redactions.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cyclopts>=4.11.2
Requires-Dist: onnxruntime>=1.16.1
Requires-Dist: pillow>=10.1
Description-Content-Type: text/markdown

# 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:

```bash
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`:

```bash
uvx vided --help
```

For frequent use, install the command persistently:

```bash
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:

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

Create a project:

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

Trim silence:

```bash
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:

```bash
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:

```bash
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`:

```bash
uvx vided render my-video --overwrite
```

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

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

Optional: render a contact sheet from the final video:

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

## Common Tasks

Trim with the default audio-level detector:

```bash
uvx vided trim my-video --overwrite
```

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

Trim with speech-aware VAD:

```bash
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:

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

Render with an audio preset:

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

Render a smaller screen-recording output with smart compression:

```bash
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.

```bash
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:

```bash
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:

```bash
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`:

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

Use a smaller trim artifact for review:

```bash
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.

```text
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:

```bash
uvx vided audio-presets
```

Choose your own preview snippet:

```bash
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:

```bash
scripts/generate_example_media.sh
```

Regenerate and upload release assets:

```bash
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:

```bash
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:

```text
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:

```bash
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:

```text
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:

```bash
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:

```bash
uv sync
uv run vided doctor
```

Run tests:

```bash
uv run pytest
```

Format, lint, and type-check:

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

Install and run pre-commit hooks:

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

Run fixture e2e tests:

```bash
uv run pytest --run-e2e -m e2e
```

Install the Playwright browser before browser e2e tests:

```bash
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.

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

After committing, add the matching tag:

```bash
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.
