# Amharc / KnottVideo
[](https://crates.io/crates/amharc)
[](https://docs.rs/amharc)
[](https://opensource.org/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:
```sh
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:
```sh
cargo install amharc --locked
knott-video
```
Codec availability depends on the installed GStreamer plugins.
## Build a source checkout
```sh
cargo build --release --locked
cargo run --release
```
To install the release binary, desktop entry, and application icon for the
current user:
```sh
./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
| `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:
```sh
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](https://docs.rs/amharc).
Release history is recorded in the
[packaged changelog](https://docs.rs/crate/amharc/latest/source/CHANGELOG.md).
## Author and license
Created by **Trevor Knott** at **Knott Dynamics**.
Licensed under the [MIT License](https://opensource.org/license/mit).