dcosnet
/
ferret
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ferret/QUICKSTART.md

5.8 KiB
Executable File
Raw Blame History

Quickstart

Get ferret running in under 5 minutes.

This guide walks you through installing dependencies, building ferret, and playing your first video. For full documentation, see README.md.

1. Install Rust

ferret requires Rust 1.75 or later. Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustc --version  # should print 1.75.0 or higher

If you already have Rust, update to the latest stable:

rustup update stable

2. Get the source

git clone http://git.dcos.net/dcosnet/ferret.git
cd ferret

3. Set up libmpv (one-time)

ferret links against libmpv 2.x. The setup-libmpv.sh script downloads the libmpv .deb packages and extracts them into a local prefix — no root required.

./scripts/setup-libmpv.sh

This takes about 30 seconds. When it finishes, source the env script:

source ./mpv-prefix/env.sh

You need to source this script in every terminal before building or running ferret (or add it to your ~/.bashrc).

What the script installs

  • libmpv2, libmpv-dev — the libmpv shared library and headers
  • libxkbcommon-x11-0, libxcb-xkb1, xkb-data — winit keyboard support
  • mesa-vulkan-drivers, libgl1-mesa-dri — GPU drivers (software fallback)
  • libclang1-19, libllvm19 — for bindgen (FFI generation)
  • xvfb, xauth — for headless testing (optional)

Verification

pkg-config --modversion mpv   # should print "2.5.0" or similar

4. Build

cargo build --release

First build takes about 2 minutes (compiles bindgen + winit + egui + wgpu). Subsequent builds are incremental.

The binary is at target/release/ferret. The build bakes in an rpath to mpv-prefix/usr/lib/x86_64-linux-gnu/, so you don't need LD_LIBRARY_PATH at runtime.

Build flags

./scripts/build.sh --debug   # debug build
./scripts/build.sh --clean   # clean + rebuild
./scripts/build.sh --test    # run cargo test
./scripts/build.sh --lint    # clippy + bracket audit + deref audit
./scripts/build.sh --ci      # full CI pass (lint + test + build)

5. Install runtime dependencies

ferret needs one external tool at runtime:

ffmpeg (for A-B loop video export)

# Debian/Ubuntu
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

ffmpeg is only needed for File → Export A-B Loop Video.... If you don't plan to use that feature, you can skip it.

File dialogs are built into the UI — no zenity, kdialog, or rfd required.

6. Play a video

./target/release/ferret /path/to/video.mp4

You should see:

  1. A dark grey window (1280×720 by default)
  2. A menu bar at the top-left: File Playback Subtitles Video Help + a status line
  3. The video starts playing immediately

If you launch with no arguments:

./target/release/ferret

You get an empty dark grey window. Click File → Load File... to open the in-UI file browser and pick a file.

7. Basic controls

Action How
Play / Pause Space, or click the ▶/⏸ button
Seek Drag the seek bar, or ← / → keys
Volume Drag the slider, or ↑ / ↓ keys
Mute M key, or click the speaker icon
Fullscreen F key, or click the ⛶ button
Quit Q key, or File → Quit

8. Try the A/B loop export

This is ferret's signature feature — extract a clip from a video using A/B markers:

  1. Play the video to the start of the segment you want.
  2. Press [ to set marker A.
  3. Play to the end of the segment.
  4. Press ] to set marker B.
  5. Click File → Export A-B Loop Video...
  6. The in-UI file browser opens — pick where to save the clip.
  7. ffmpeg runs in the background and renders the segment.

You'll see red and blue pins on the seek bar marking A and B. An info toast appears when the export is done.

9. Load a folder as a playlist

File → Load Folder... → pick a directory

ferret scans the folder for video files (.mp4, .mkv, .webm, .avi, .mov, .flv, .mp3, .ogg, .wav, .flac, etc.), sorts them alphabetically, and loads them as a playlist. Use N / P keys (or the ⏭ / ⏮ buttons) to move between entries.

To loop the whole playlist: Playback → Loop → Loop Playlist.

Troubleshooting

"failed to locate libmpv via pkg-config"

You forgot to source the env script:

source ./mpv-prefix/env.sh

"libmpv.so.2: cannot open shared object file"

Same fix — source the env script. Or set LD_LIBRARY_PATH manually:

export LD_LIBRARY_PATH=./mpv-prefix/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH

"ffmpeg not found in PATH"

Install ffmpeg (see step 5). This only affects A-B loop video export.

Window opens but is transparent / shows desktop

This happens when no video is loaded — the overlay clears to dark grey (#1a1a1d). If you're seeing the desktop instead, make sure you're running on X11 (Wayland is not yet supported — see README.md).

File dialogs don't appear

File dialogs are built into the ferret UI — no external tools needed. If the dialog doesn't open, check that the overlay is receiving mouse events (move the mouse over the window).

Next steps

Uninstall

ferret doesn't install anything system-wide. To remove:

rm -rf /path/to/ferret           # removes source + build + mpv-prefix

The mpv-prefix/ directory contains the extracted libmpv packages — it's self-contained and safe to delete.