pandaflix

README

PANDAFLIX

Spiritual successor of flix-cli and mov-cli.

---

---

Overview

• Installation
  • Arch Linux
  • NixOS / Nix / MacOS
  • Debian-based or Ubuntu-based
  • Fedora
  • MacOS
  • Windows
  • Go Install
  • Build from Source
  • Android Installation
• Dependencies
• Usage
  • Flags
  • Playback Controls
  • Examples
• Configuration
• Hooks & MpvArgs
  • MpvArgs
  • Hooks
• Providers

[!NOTE] Before creating an issue, make sure to update pandaflix

Installation

1. Arch Linux

paru -S pandaflix-bin

2. NixOS / Nix / MacOS

Run without installing

nix run github:DemonKingSwarn/pandaflix

Install into profile

nix profile install github:DemonKingSwarn/pandaflix

NixOS flake input

inputs.pandaflix.url = "github:DemonKingSwarn/pandaflix";

environment.systemPackages = [ inputs.pandaflix.packages.${system}.pandaflix ];

3. Debian-based or Ubuntu-based

curl -fsSL https://demonkingswarn.is-a.dev/debmon-repo/pubkey.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/debmon-repo.gpg

echo "deb [arch=amd64] https://demonkingswarn.is-a.dev/debmon-repo stable main" | sudo tee /etc/apt/sources.list.d/debmon-repo.list

sudo apt update

sudo apt install -y pandaflix

4. Fedora

echo '[fedmon-repo]
name=fedmon-repo
baseurl=https://demonkingswarn.is-a.dev/fedmon-repo/rpms
enabled=1
gpgcheck=1
gpgkey=https://demonkingswarn.is-a.dev/fedmon-repo/pubkey.gpg' | sudo tee /etc/yum.repos.d/fedmon-repo.repo

sudo dnf update

sudo dnf install -y pandaflix

5. MacOS

brew tap gamedevCloudy/tools
brew install --cask iina
brew install pandaflix

6. Windows

Make sure you have scoop.sh installed on your system.

scoop bucket add demon-apps https://github.com/DemonKingSwarn/flix-cli-bucket.git
scoop bucket add extras
scoop install pandaflix

[!IMPORTANT] On windows if you want to use the --show-image, you need to use the wezterm terminal emulator. It is installed as a dependency on windows.

7. Go Install

If you have Go installed, you can easily install Pandaflix:

go install github.com/MADPANDA3D/pandaflix@latest

8. Build from Source

1. Clone the repository:

   git clone https://github.com/MADPANDA3D/pandaflix.git
   cd pandaflix
   

2. Build and install:

   go install .
   

   Ensure your $GOPATH/bin is in your system's PATH.

9. Android Installation

Install termux (Guide)

pkg up -y
pkg in fzf python-yt-dlp
curl -sL "https://github.com/DemonKingSwarn/pandaflix/releases/download/v1.2.1/pandaflix-android-arm64" -o $PREFIX/bin/pandaflix
chmod +x $PREFIX/bin/pandaflix

Dependencies

• mpv - Video Player for Linux and Windows
• vlc - Alternate video player for Linux and Windows
• iina - Video Player for MacOS
• mpv-android - Video Player for Android
• yt-dlp - Download manager
• fzf - For selection menus
• chafa & libsixel - For poster previews (--show-image)

Usage

pandaflix [query] [flags]

[query] is the title you want to search for (e.g., "breaking bad", "dune", "one piece"). The query is optional when using --history or --recommend.

Flags

Flag	Alias	Description
--action	-a	Action to perform: play (default) or download.
--season	-s	(Series only) Specify the season number.
--episodes	-e	(Series only) Specify a single episode (5) or a range (1-5).
--best	-b	Auto-select the best available quality (skips fzf quality prompt).
--provider	-p	Select provider (e.g. sflix, braflix). Overrides config.
--history	-H	Browse watch history and resume a previous title.
--recommend	-r	Get personalised recommendations based on watch history.
--show-image	true	Show poster previews in fzf (requires chafa; skipped automatically when missing). Disable with --show-image=false.
--debug	-d	Print debug information (URLs, decryption steps, etc.).
--help	-h	Show help message and exit.

Playback Controls

When watching a TV series, an fzf menu appears alongside the player with four options:

Action	Description
Next	Kill the player and move to the next episode.
Previous	Kill the player and move to the previous episode.
Replay	Restart the current episode from the beginning.
Quit	Kill the player and exit.

Examples

Search & Play a Movie

pandaflix "dune"

Download a Movie

pandaflix "dune" --action download

Play a TV Episode

pandaflix "breaking bad" -s 1 -e 1

Download a Range of Episodes

pandaflix "stranger things" -s 2 -e 1-5 -a download

Auto-select Best Quality

pandaflix "dune" --best

Use a Different Provider

pandaflix "breaking bad" --provider sflix

Resume from Watch History

pandaflix --history

Get Personalised Recommendations

pandaflix --recommend

Recommendations with Poster Previews

pandaflix --recommend --show-image

Configuration

The config file lives at ~/.config/pandaflix/config.yaml. All fields are optional; defaults are shown below.

# Path to the fzf binary. Set to an absolute path if fzf is not on PATH.
fzf_path: fzf

# Video player: "mpv" (default) or "vlc". IINA is used automatically on macOS.
player: mpv

# chafa rendering backend for poster previews.
# Options: sixel (default), kitty, iterm, symbols
image_backend: sixel

# Default search provider.
provider: flixhq

# Directory where downloaded files are saved. Defaults to home directory.
dl_path: ""

# Quality selection: leave empty to show an fzf prompt, or set to "best"
# to always auto-select the highest available quality.
quality: ""

# Hide the terminal window while the player is open and restore it when
# playback ends (Hyprland via hyprctl, other Linux via xdotool).
minimize_on_play: true

# Shift audio relative to video (seconds; positive delays audio, negative
# advances it) — use if a stream's audio plays slightly early/late.
audio_delay: 0

# Extra arguments appended to every mpv invocation (ignored on VLC/IINA/Android).
# mpv_args:
#   - "--hwdec=auto"
#   - "--volume=80"

# Lifecycle hooks — shell commands run at key playback events.
# LUFFY_TITLE, LUFFY_URL, LUFFY_SEASON, LUFFY_EPISODE, LUFFY_EP_NAME,
# LUFFY_PROVIDER, LUFFY_ACTION, LUFFY_STREAM_URL, and LUFFY_POSITION
# are set in the environment for every hook.
# hooks:
#   on_play: 'notify-send "Now playing" "$LUFFY_TITLE"'
#   on_exit: 'echo "$LUFFY_TITLE stopped at ${LUFFY_POSITION}s" >> ~/pandaflix.log'
#   on_download: 'notify-send "Downloading" "$LUFFY_TITLE"'

[!IMPORTANT] To see poster images, your terminal emulator must support a graphics protocol. Supported terminals include kitty, ghostty, WezTerm, and foot (sixel).

kitty, ghostty, and WezTerm are auto-detected; set image_backend in config only to override the detected format.

Hooks & MpvArgs

Shell commands can be run at three lifecycle points, and extra mpv flags can be injected via config. See docs/hooks.md for the full reference.

MpvArgs

Extra arguments appended verbatim to every mpv invocation (ignored on VLC / IINA / Android):

mpv_args:
  - "--hwdec=auto"
  - "--volume=80"

Hooks

hooks:
  on_play: 'notify-send "Now playing" "$LUFFY_TITLE"'
  on_exit: 'echo "$LUFFY_TITLE stopped at ${LUFFY_POSITION}s" >> ~/pandaflix.log'
  on_download: 'notify-send "Downloading" "$LUFFY_TITLE"'

Every hook receives LUFFY_TITLE, LUFFY_URL, LUFFY_SEASON, LUFFY_EPISODE, LUFFY_EP_NAME, LUFFY_PROVIDER, LUFFY_ACTION, LUFFY_STREAM_URL, and LUFFY_POSITION as environment variables.

Providers

You can set the default provider in the config file (~/.config/pandaflix/config.yaml) or override it per-run with --provider.

Provider	provider: value	Content	Notes
Cinejoy	cinejoy	Movies & TV	Default. Browser-free sealed resolver; auto-races Lisbon/Nebula/Solara.
VixSrc	vixsrc	Movies & TV	Independent backup. Listed in the Servers menu; also used automatically when Cinejoy fails.
Anime (sub)	anime or allanime	Anime	Subtitled. Uses AllAnime.
Anime (dub)	anime-dub or allanime-dub	Anime	Dubbed. Uses AllAnime.

Legacy cineby/vidking/videasy configs keep working and resolve via Cinejoy; the Videasy backend is being discontinued. Example config:

provider: cinejoy

---

Debugging

Run any command with --debug (-d) to print detailed information:

pandaflix "breaking bad" -s 1 -e 1 --debug

Debug output includes:

• The embed URL being resolved
• The master m3u8 URL
• The referer header used
• Number of subtitle tracks found
• The exact mpv command being run

If playback fails, the debug output is almost always enough to diagnose the problem.

---

Before Opening an Issue

Please try these steps first:

1. Update pandaflix — most issues are already fixed in the latest version.

   go install github.com/MADPANDA3D/pandaflix@latest
   

2. Run with --debug and read the output — it usually tells you exactly what failed.

3. Try a different title — the content may be unavailable on the provider.

4. Check the Discord — someone may have already reported the same issue.

If none of the above helps, open an issue and include:

• The exact command you ran
• The full --debug output
• Your OS and pandaflix version (pandaflix --version if available, or git log -1 --oneline)
• Whether the issue is with a movie or TV show, and the title