Amharc / KnottVideo

amharc is the Cargo distribution of KnottVideo, a native Rust video player for Linux built with GTK4 and GStreamer. It combines a cinematic desktop viewer, a searchable local playlist, and a compact floating widget in one offline-first application.

The installed executable is named knott-video so existing desktop launchers, session data, and Open With integration remain compatible.

Highlights

• Embedded local playback with loading, buffering, end-of-stream, and recoverable error states.
• Multi-file open and drag-and-drop queue with search, reordering, automatic progression, finite shuffle cycles, repeat modes, and undo.
• A persistent media workspace with multiple recursive video folders, fast folder switching, queue merging, and reusable named playlists.
• Precise scrubbing, 10/60-second seeking, frame stepping, jump-to-time, and A–B looping, plus persistent named points for returning to exact moments.
• A responsive fullscreen viewer and a compact, adjustable-opacity widget mode.
• Five persistent, live-switching cinema themes that retune the entire player, with motion that follows the desktop reduced-animation preference.
• Persistent playlist, resume positions, volume, mute, speed, subtitles, repeat/shuffle state, queue visibility, pinning, and window opacity.
• External SRT, VTT, ASS, SSA, and SUB subtitles with sidecar discovery.
• PNG frame snapshots, video-path copying, and containing-folder access.
• Local-only playback: KnottVideo does not upload media or require an account.

Install from crates.io

KnottVideo uses native GTK4 and GStreamer libraries. On Ubuntu or Debian, install the build and runtime dependencies first:

sudo apt install build-essential pkg-config libgtk-4-dev \
  libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
  gstreamer1.0-libav

Then install the release from crates.io and launch it:

cargo install amharc --locked
knott-video

Codec availability depends on the installed GStreamer plugins.

Build a source checkout

cargo build --release --locked
cargo run --release

To install the release binary, desktop entry, and application icon for the current user:

./scripts/install.sh

The script installs the binary under ${XDG_BIN_HOME:-$HOME/.local/bin} and desktop assets under ${XDG_DATA_HOME:-$HOME/.local/share}. Remove those files with ./scripts/uninstall.sh. A plain cargo install installs only the binary.

Widget mode

Press Ctrl+M or select Widget to collapse KnottVideo into a focused floating viewer. Widget mode keeps essential transport, timeline, speed, subtitle, pin, and opacity controls close to the video while hiding the queue and application chrome. Move the pointer or use the keyboard to reveal controls; they retract during playback to preserve the image.

Workspace, themes, playlists, and saved points

Select Workspace or press Ctrl+Shift+O to open the media workspace. Add as many local video folders as you need; KnottVideo scans supported files in each folder and its subfolders without following directory symlinks. Load flips the player to that folder, while Add merges its videos into the current queue. Removing a folder from the workspace never deletes media from disk.

The Appearance page includes Signal Cyan, Aurora Jade, Ember Cinema, Ultraviolet, and Moonstone. A selection is applied live across the desktop player, compact widget, dialogs, focus rings, glows, and controls, then saved automatically. Press Ctrl+, to open Appearance directly. Interface entrances, hover transitions, and palette-change effects honor GTK's system animation setting, including reduced-motion configurations.

The Playlists page saves the current queue under a name. A playlist can be loaded, updated from the current queue, or deleted independently of its source folders. Unavailable files are skipped safely when a playlist is loaded.

From Video tools, save named points such as “Intro” or “Favorite scene.” Points are stored per video, remain available across sessions, and can be selected directly or flipped backward and forward with Ctrl+Left and Ctrl+Right.

Always-on-top uses the EWMH _NET_WM_STATE_ABOVE hint and currently requires an X11 session with a compatible window manager. Playback and the remaining viewer features continue to work when that hint is unavailable.

Keyboard shortcuts

Supported media

The player recognizes MP4/M4V, Matroska, WebM, AVI, MOV, MPEG, Ogg, transport stream, FLV, WMV, and 3GP files. Actual decoding support is provided by the local GStreamer installation.

Development and documentation

The standard release gates are:

cargo fmt --all -- --check
cargo test --locked
cargo clippy --all-targets --locked -- -D warnings
cargo doc --no-deps --no-default-features --locked
cargo package --locked

API and package documentation is published at docs.rs/amharc. Release history is recorded in the packaged changelog.

Author and license

Created by Trevor Knott at Knott Dynamics.

Licensed under the MIT License.