amharc 0.1.0

A cinematic GTK4 and GStreamer desktop video player with a floating widget mode
Documentation

Amharc / KnottVideo

Crates.io Documentation License: MIT

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.
  • Precise scrubbing, 10/60-second seeking, frame stepping, jump-to-time, and A–B looping.
  • A responsive fullscreen viewer and a compact, adjustable-opacity widget mode.
  • 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.

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

Key Action
Space / K Play or pause
Left / J, Right / L Seek backward or forward 10 seconds
Shift+Left / Shift+J, Shift+Right / Shift+L Seek backward or forward 60 seconds
Up / Down Raise or lower volume
Home / End Seek to the beginning or end
P / N Previous or next video
S Toggle shuffle
R Cycle repeat off, playlist, and current video
Q Show or hide the playlist
. Advance one frame
A / B Set A–B loop points; press again to clear
T Toggle always-on-top
[ / ] Decrease or increase window opacity
Ctrl+T Jump to a time
Ctrl+O Add videos
F / Escape Enter or leave fullscreen
M Mute or restore audio
Ctrl+M Toggle widget mode
Ctrl+R Cycle playback speed
Ctrl+Shift+S Save the current frame as PNG
Ctrl+Up / Ctrl+Down Move the selected video
Delete Remove the selected video
Ctrl+Delete Clear the playlist
? Show the in-app shortcut guide

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.