Docs

Every feature is reachable from the GUI, the CLI, and the MCP server. The reference below covers all three.

Command names, flags, and JSON keys are kept in English so they match what you actually type. The surrounding explanations are translated.

Generated from unflick v0.15.0

Quick start

Install

One line on any platform (see the home page), Homebrew on macOS, or an installer from the download section. The Windows AI Edition also bundles an offline Whisper model for zero-config subtitles.

Try it from a terminal

# Open a file (or a YouTube URL)
unflick play movie.mp4

# Jump to the next chapter, then save a bookmark
unflick chapter next
unflick bookmark add --name "the good bit"

# Cut a 30-second GIF starting at 00:01:00
unflick clip 60 90 --file movie.mp4 --gif

# Find subtitles online, or generate them locally (AI edition: zero config)
unflick subtitle auto
unflick subtitle generate movie.mp4

Drop it into an AI client

Add this snippet to your MCP client config (Claude Desktop, Cursor, Codex CLI, etc.) and the agent gains 101 tools and 3 live resources to drive playback, generate subtitles, scan your library, and more.

{
  "mcpServers": {
    "unflick": {
      "command": "unflick",
      "args": ["--mcp"]
    }
  }
}

On Windows, use the full path: "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\unflick\\unflick.exe"

Claude Code plugin

In Claude Code, these two commands install seven unflick skills and wire up the MCP server in one step.

/plugin marketplace add zhitongblog/unflick
/plugin install unflick

CLI reference

The CLI returns JSON on stdout for every command. Pipe through jq, parse it from a script, automate freely. Subcommands auto-launch the background daemon on first use.

Playback

`unflick play [--seek <SEEK>] [--volume <VOLUME>] [--speed <SPEED>] <FILE>`	Play a video file
`unflick pause`	Pause playback
`unflick resume`	Resume playback
`unflick stop`	Stop playback
`unflick seek <SECONDS>`	Seek to position in seconds
`unflick volume <LEVEL>`	Set volume (0-100)
`unflick speed [--relative] [RATE]`	Get or set the playback speed
`unflick status`	Get current playback status
`unflick chapter list`	List all chapters of the current file
`unflick chapter seek <INDEX>`	Jump to a chapter by 0-based index
`unflick chapter next`	Jump to the next chapter
`unflick chapter prev`	Jump to the previous chapter
`unflick chapter generate [--count <COUNT>]`	Derive chapters from the transcript, for a file that has none
`unflick chapter set <JSON>`	Set chapters explicitly from JSON: [{"time": 0, "title": "Intro"}, …]
`unflick chapter clear`	Remove generated chapters (container chapters are untouched)
`unflick loop a [POSITION]`	Set the loop start point (defaults to the current position)
`unflick loop b [POSITION]`	Set the loop end point (defaults to the current position)
`unflick loop clear`	Clear both loop points
`unflick loop status`	Show the current loop points
`unflick frame next`	Step forward one frame (pauses playback)
`unflick frame prev`	Step back one frame (pauses playback)
`unflick frame thumbnail [--output <OUTPUT>] [--width <WIDTH>] <POSITION>`	Save the timeline preview frame for a position (cached, keyframe-accurate)
`unflick frame capture [--output <OUTPUT>] [--position <POSITION>] [--max-edge <MAX_EDGE>]`	Save the current frame as a downscaled JPEG
`unflick bookmark add [--name <NAME>] [--position <POSITION>] [--file <FILE>]`	Save a position — where playback is now, unless told otherwise
`unflick bookmark list [--file <FILE>] [--key <KEY>] [--all]`	Show bookmarks for the current file
`unflick bookmark goto <ID>`	Jump to a bookmark, opening its file if it isn't the one playing
`unflick bookmark rename [--clear] <ID> [NAME]`	Rename a bookmark, or drop its name with `--clear`
`unflick bookmark remove <ID>`	Delete one bookmark
`unflick bookmark clear [--file <FILE>] [--key <KEY>] [--all]`	Delete every bookmark for the current file
`unflick session show`	Report what would be resumed (the default)
`unflick session restore`	Reopen it, at the point it got to
`unflick session clear`	Forget it
`unflick recent list [--limit <LIMIT>]`	Show recently played files, newest first
`unflick recent clear`	Forget the play history (scanned metadata is kept)
`unflick incognito [ENABLED]`	Turn incognito on or off (nothing is written to the play history)

Media tools

`unflick info <FILE>`	Get media file info
`unflick screenshot [--output <OUTPUT>]`	Take a screenshot of the current frame
`unflick clip [--file <FILE>] [--output <OUTPUT>] [--gif] <START> <END>`	Extract a video clip (requires ffmpeg)
`unflick transcript get`	Print every cue of the current file's transcript
`unflick transcript search [--limit <LIMIT>] <QUERY>`	Find lines containing a phrase
`unflick transcript seek [--occurrence <OCCURRENCE>] <QUERY>`	Jump to where a phrase is spoken
`unflick nowplaying [--cover]`	What is playing, as tags rather than a path

Subtitles & audio

`unflick subtitle load <FILE>`	Load an external subtitle file
`unflick subtitle list`	List subtitle tracks
`unflick subtitle select <ID>`	Select a subtitle track by ID (0 to disable)
`unflick subtitle generate [--mode <MODE>] [--whisper <WHISPER>] [--model <MODEL>] [--api-key <API_KEY>] [--output-dir <OUTPUT_DIR>] <VIDEO>`	Generate subtitles for a video using whisper (local or OpenAI API)
`unflick subtitle translate [--to <TARGET_LANG>] [--api-key <API_KEY>] [--output-dir <OUTPUT_DIR>] --to <TARGET_LANG> --api-key <API_KEY> <SRT>`	Translate an SRT file to another language via OpenAI API
`unflick subtitle search [--file <FILE>] [--lang <LANGUAGES>] [--no-hash] [QUERY]`	Find subtitles for the playing file on OpenSubtitles
`unflick subtitle download [--file <FILE>] [--lang <LANGUAGE>] [--name <NAME>] [--no-load] <FILE_ID>`	Download a subtitle found by `subtitle search` and load it
`unflick subtitle auto [--file <FILE>] [--lang <LANGUAGES>] [--no-hash] [--no-load] [QUERY]`	Search and download the best match in one step
`unflick subtitle delay [--relative] [SECONDS]`	Get or set the subtitle delay. Positive values show subtitles later
`unflick subtitle style get`	Print all subtitle style values
`unflick subtitle style set <NAME> <VALUE>`	Set one style property
`unflick subtitle bilingual [--primary <PRIMARY>] [--secondary <SECONDARY>] [--layout <LAYOUT>] [STATE]`	Show two subtitle tracks at once — the original and a translation
`unflick audio list`	List all audio tracks
`unflick audio select <ID>`	Select an audio track by ID (0 to disable)
`unflick audio delay [--relative] [SECONDS]`	Get or set the audio delay. Positive values play audio later
`unflick audio eq get`	Show the current curve, preamp and normalisation state
`unflick audio eq on`	Turn the equaliser on or off without discarding the curve
`unflick audio eq off`
`unflick audio eq band <INDEX> <GAIN>`	Set one band's gain in dB
`unflick audio eq curve [GAINS] [GAINS] [GAINS] [GAINS] [GAINS] [GAINS] [GAINS] [GAINS] [GAINS] [GAINS]...`	Set the whole curve at once
`unflick audio eq preamp <DB>`	Set the preamp in dB (negative makes headroom for boosted bands)
`unflick audio eq normalize <STATE>`	Even out quiet dialogue against loud action
`unflick audio eq preset [NAME]`	Apply a named preset
`unflick audio eq reset`	Clear every audio filter
`unflick audio pitch [STATE]`	Keep the original pitch when playback speed changes

Picture & window

`unflick video get`	Show the current aspect, rotation, zoom, pan-scan and deinterlace
`unflick video set <NAME> <VALUE>`	Set one: aspect \| rotate \| zoom \| panscan \| deinterlace
`unflick video reset`	Back to the file's own geometry
`unflick filter list`	Show all current filter values (brightness, contrast, saturation, gamma, hue)
`unflick filter set <NAME> <VALUE>`	Set a filter to the given value (-100 to 100)
`unflick filter reset`	Reset all filters to 0 (neutral)
`unflick window mode [MODE]`	Read or set the window mode

Playlist & library

`unflick playlist add <FILE>`	Add a file to the playlist
`unflick playlist remove <INDEX>`	Remove entry at index
`unflick playlist list`	List all playlist entries
`unflick playlist next`	Play the next track
`unflick playlist prev`	Play the previous track
`unflick playlist clear`	Clear the playlist
`unflick playlist play <INDEX>`	Play a specific entry by index
`unflick playlist repeat [MODE]`	Get or set the repeat mode
`unflick playlist shuffle [ENABLED]`	Get or set shuffle
`unflick library scan <DIR>`	Scan a directory for video files and add them to the library
`unflick library search <QUERY>`	Search the library by title or path
`unflick library list`	List all media in the library
`unflick library remove <ID>`	Remove an entry by ID

Streams, discs & casting

`unflick sponsor list <URL>`	Fetch SponsorBlock segments for a YouTube URL and print them as JSON. 404 / no-segments returns an empty list (success)
`unflick sponsor enable`	Turn SponsorBlock auto-skip on (writes settings)
`unflick sponsor disable`	Turn SponsorBlock auto-skip off (writes settings)
`unflick sponsor categories <LIST>`	Replace the SponsorBlock category list (comma-separated, e.g. `sponsor,selfpromo,intro,outro,interaction`)
`unflick disc [PATH]`	Optical drives, and whether there is a video disc in them
`unflick cast list [--seconds <SECONDS>]`	Find DLNA renderers on the network
`unflick cast to [--file <FILE>] [--seconds <SECONDS>] [RENDERER]`	Send what is playing (or a named file) to a renderer
`unflick cast stop`	Stop casting
`unflick cast status`	Where the cast has got to
`unflick cast pause`
`unflick cast resume`
`unflick cast seek <SECONDS>`	Seek the cast, in seconds

Input

`unflick keybind list`	List every bindable action with its current key
`unflick keybind set <ACTION> <KEY>`	Bind a key to an action, e.g. `keybind set play_pause k`
`unflick keybind reset [ACTION]`	Restore defaults — one action, or all of them
`unflick mouse list`	List every mouse trigger with the action it runs
`unflick mouse set <TRIGGER> <ACTION>`	Point a trigger at an action, e.g. `mouse set wheel_up volume_up`
`unflick mouse reset [TRIGGER]`	Restore defaults — one trigger, or all of them

Settings

`unflick settings path`	Print the absolute path to the settings file
`unflick settings get [--key <KEY>]`	Print all settings (or a single key with --key)
`unflick settings set <KEY> <VALUE>`	Set a single key to the given JSON value
`unflick settings unset <KEY>`	Remove a single key

Daemon & diagnostics

`unflick daemon`	Start the background daemon (holds the player instance)
`unflick --mcp`	Start the MCP server over stdio. See the MCP reference below.
`unflick shutdown`	Shut down the daemon
`unflick startup`	The last launch's startup timeline, phase by phase
`unflick cleanup [--apply]`	Find (and optionally remove) files an older unflick left behind
`unflick dev eval [--timeout <TIMEOUT>] <SCRIPT>`	Run JavaScript in the window and print what it evaluated to
`unflick dev click [--index <INDEX>] [--timeout <TIMEOUT>] <SELECTOR>`	Click an element, after checking it is really the thing on top
`unflick dev text <SELECTOR>`	Visible text of every element matching a selector
`unflick dev snapshot [--selector <SELECTOR>] [--depth <DEPTH>]`	The accessibility tree of the window: role, name, state, selector
`unflick dev capture [--output <OUTPUT>] [--max-edge <MAX_EDGE>]`	A PNG of the interface layer
`unflick dev wait [--gone] [--timeout <TIMEOUT>] <SELECTOR>`	Wait for an element to appear — or, with --gone, to leave

MCP reference

unflick exposes a Model Context Protocol server over stdio when launched with --mcp. Every CLI capability is also a tool, plus three subscribable resources for state.

Tools (101)

`play`	Play a video file or URL.
`pause`	Pause playback.
`resume`	Resume playback after a pause.
`stop`	Stop playback and unload the file.
`seek`	Seek to a position in seconds
`set_volume`	Set volume level
`set_speed`	Get or set the playback speed of the window the user is watching.
`get_status`	Get current playback status including state, file, position, duration, volume, and speed.
`file_info`	Get media file metadata (duration, resolution, codecs) without affecting current playback
`playlist_add`	Add a file to the playlist
`playlist_remove`	Remove a playlist entry by index
`playlist_list`	List all playlist entries with index, path, and current track indicator
`playlist_next`	Advance to and play the next track in the playlist
`playlist_prev`	Go back to and play the previous track in the playlist
`playlist_clear`	Clear all entries from the playlist
`playlist_play`	Play a specific playlist entry by index
`load_subtitle`	Load an external subtitle file
`subtitle_list`	List all subtitle tracks (embedded and external)
`subtitle_select`	Select a subtitle track by ID (0 to disable subtitles).
`audio_list`	List all audio tracks (embedded)
`audio_select`	Select an audio track by ID (0 to disable audio)
`generate_subtitles`	Generate subtitles for a video using whisper.
`translate_subtitles`	Translate an SRT file to another language using OpenAI.
`library_scan`	Scan a directory for video files and add them to the library
`library_search`	Search the media library by title or path
`library_list`	List all media files in the library
`library_remove`	Remove a media entry from the library by ID
`clip`	Extract a video clip segment, optionally as GIF.
`screenshot`	Take a screenshot of the current video frame
`save_position`	Save playback position for a file (for resume playback)
`get_position`	Get saved playback position for a file
`settings_path`	Get the absolute path of the settings.json file
`settings_get`	Read all settings, or a single key if provided
`settings_set`	Set a single settings key to the given JSON value
`settings_unset`	Remove a single settings key
`filter_list`	List current video filter values (brightness, contrast, saturation, gamma, hue)
`filter_set`	Set a video filter (brightness \| contrast \| saturation \| gamma \| hue) to a value in -100..100
`filter_reset`	Reset all video filters to 0 (neutral)
`sponsor_segments`	Fetch SponsorBlock skip segments for a YouTube URL.
`subtitle_delay`	Get or set the subtitle delay in seconds.
`audio_delay`	Get or set the audio delay in seconds, for fixing lip-sync.
`subtitle_style_get`	Read subtitle appearance: scale, vertical position, colour, border size, bold.
`subtitle_style_set`	Set one subtitle appearance property.
`subtitle_bilingual`	Show two subtitle tracks at once — typically the original plus a translation.
`chapter_list`	List the chapters of the currently playing file: index, title, start time, and which one is playing.
`chapter_seek`	Jump to a chapter by 0-based index.
`chapter_next`	Jump to the next chapter.
`chapter_prev`	Jump to the previous chapter.
`ab_loop`	Control the A-B loop, which repeats a section of the current file.
`frame_step`	Step forward exactly one frame.
`frame_back_step`	Step back exactly one frame.
`playlist_repeat`	Get or set the playlist repeat mode.
`playlist_shuffle`	Get or set playlist shuffle.
`shutdown`	Shut down the unflick daemon.
`get_subtitles`	Find and load subtitles for the playing video from OpenSubtitles, in one step.
`find_subtitles`	Search OpenSubtitles and return the candidates without downloading anything.
`download_subtitle`	Download one subtitle chosen from find_subtitles and load it into the player.
`search_transcript`	Search the currently playing file's subtitles for a phrase and return every match with its timestamp.
`seek_to_text`	Jump playback to where a phrase is spoken.
`transcript_get`	Return the full transcript of the currently playing file as timed cues, plus where it came from.
`generate_chapters`	Give a file that has no chapters a set of them, derived from the pauses in its transcript.
`set_chapters`	Set the chapter list for a file that has none, from your own reading of its content.
`clear_chapters`	Remove chapters added by generate_chapters or set_chapters.
`keybind_list`	List every keyboard shortcut: action id, label, current key, default, and whether the user has changed it.
`keybind_set`	Rebind a keyboard shortcut.
`keybind_reset`	Restore a shortcut to its default.
`video_transform_get`	Read how the picture is fitted to the window: aspect override, rotation, zoom multiplier, pan-scan and deinterlace.
`video_transform_set`	Fix a squashed aspect ratio, straighten a video recorded sideways, crop black bars, or deinterlace broadcast footage.
`video_transform_reset`	Restore the file's own geometry — no aspect override, no rotation, no zoom or pan-scan, deinterlace off.
`incognito`	Read or set incognito mode.
`recent_files`	Recently played files, newest first, with how many times each was played and when.
`recent_clear`	Forget the play history.
`bookmark_add`	Save a named position in a file, so it can be jumped back to later.
`bookmark_list`	Bookmarks for the file being watched, in timeline order.
`bookmark_goto`	Jump to a bookmark by id.
`bookmark_rename`	Give a bookmark a name, or drop the one it has by omitting name.
`bookmark_remove`	Delete one bookmark by id.
`bookmark_clear`	Delete every bookmark for the file being watched, or for the file named.
`mouse_list`	List mouse bindings: wheel up/down, click, double click, middle click, and the four right-drag gestures, each with the action it runs.
`mouse_set`	Point a mouse trigger at an action.
`mouse_reset`	Restore a mouse trigger to its default.
`describe_frame`	Return the frame showing right now as an image, so you can see what is on screen.
`equalizer_get`	Read the 10-band equaliser: per-band gains in dB, the band centre frequencies they correspond to, the preamp, whether loudness normalisation is on, and the filter chain mpv is actually running.
`equalizer_set`	Adjust the equaliser.
`equalizer_preset`	Apply a named equaliser curve and switch the equaliser on.
`equalizer_presets`	List the available equaliser presets with a description of what each is for and the curve it applies.
`equalizer_reset`	Remove every audio filter: flat curve, no preamp, no normalisation.
`pitch_correction`	Read or set whether changing playback speed keeps the original pitch.
`window_mode`	Get or set the shape of the player window the user is looking at.
`cleanup`	Find files an older unflick left behind — on Windows, upgrading from v0.9 moved the install directory and stranded roughly half a gigabyte with no uninstall entry.
`cast`	Send what is playing to a television on the network over DLNA.
`disc_list`	Optical drives on this machine and whether each holds a DVD or Blu-ray, plus whether this build can play them at all.
`session`	What the user was last watching and how far in — and, with action "restore", reopen it there.
`startup`	The last launch's startup timeline, phase by phase, in milliseconds from process start — process init, video pipeline, window shown, the launch file opening, React mounting, the control port.
`now_playing`	What is playing, described the way a person would: title, artist, album, and whether there is any picture (an embedded cover is not video).
`dev_snapshot`	The accessibility tree of the unflick window: every visible element with its role, accessible name, state and a CSS selector that feeds straight back into dev_click and dev_text.
`dev_click`	Click an element in the unflick window.
`dev_text`	Visible text of every element matching a selector, each with its index.
`dev_wait`	Wait for an element to appear, or with `gone` for it to leave the page.
`dev_capture`	A picture of the unflick interface.
`dev_eval`	Run JavaScript in the unflick window and get back what it evaluated to.

Resources (3)

`unflick://now-playing`	Current playback state: file, position, duration, volume, speed
`unflick://playlist`	Current playlist entries with current-track indicator
`unflick://library`	All media files in the library