plexclip 1.2.0

Download videos from Plex Media Server
Documentation

plexclip

A Rust CLI tool to download videos from Plex Media Server with support for direct downloads and HLS transcoding.

Issues can be reported at https://todo.sr.ht/~jacky/plexclip.

Features

  • Direct Downloads: Download original media files without transcoding
  • HLS Transcoding: Server-side transcoding with configurable quality/bitrate
  • Time Range Selection: Download specific segments of videos
  • Interactive Selection: Browse and select media from your Plex library
  • Multiple Formats: Support for MP4, MKV, TS, and more
  • Shell Completions: Auto-generated bash/zsh completions

Installation

From Source

git clone https://git.sr.ht/~jacky/plexclip
cd plexclip
cargo build --release

The binary will be at target/release/plexclip.

Pre-built Binaries

Download the latest release from the Releases page.

Quick Start

1. Configure Authentication

Interactive Terminal Input (Recommended)

# Interactive terminal input for token and server
plexclip auth --terminal --server http://localhost:32400

Manual Token Input

# Add your Plex server and token
plexclip auth --server http://localhost:32400 --token YOUR_PLEX_TOKEN

Help with Token Acquisition

# Get interactive help for obtaining your Plex token
plexclip auth --login

2. Download a Video

# Interactive selection (browse your library)
plexclip download --list

# Download by rating key
plexclip download 12345 -o video.mp4

# Download by Plex Web URL
plexclip download "https://app.plex.tv/desktop#!/server/abc.../details?key=/library/metadata/12345" -o video.mp4

3. Download with Time Range

# Download from 1 minute to 2 minutes 30 seconds
plexclip download 12345 --start 00:01:00 --end 00:02:30 -o clip.mp4

# Download first 5 minutes
plexclip download 12345 --start 0 --duration 00:05:00 -o clip.mp4

4. Open After Download

# Download and open with default player
plexclip download 12345 --open -o video.mp4

Commands

Download

Download videos from Plex Media Server:

plexclip download <URL> [OPTIONS]

Options:
  -o, --output <FILE>       Output file path
  -f, --format <FORMAT>     Output format (mp4, mkv, ts, webm) [default: mp4]
      --start <START>        Start time (HH:MM:SS or seconds)
  -e, --end <END>          End time (HH:MM:SS or seconds)
  -d, --duration <TIME>     Duration to download
      --direct              Download original file (no transcode)
      --transcode           Force transcoding
  -r, --resolution <RES>   Transcode resolution [default: 1920x1080]
  -b, --bitrate <KBPS>     Max bitrate in kbps [default: 8000]
  -q, --quality <0-100>    Transcode quality [default: 75]
      --open               Open the file after download
      --yes                 Overwrite without asking
      --debug              Show debug output (HTTP requests/responses)
      --verbose, -v        Increase verbosity (use multiple times: -v, -vv, -vvv)

Info

Display information about a media item:

plexclip info <URL>

Auth

Manage authentication:

# Interactive terminal token input (recommended)
plexclip auth --terminal --server http://localhost:32400

# Set token manually
plexclip auth --token YOUR_TOKEN --server http://localhost:32400

# Show current configuration
plexclip auth

Servers

List configured servers:

plexclip servers

Supported URL Formats

  • Rating Key: 12345
  • Library Path: /library/metadata/12345
  • Plex Web URL: https://app.plex.tv/desktop#!/server/abc.../details?key=/library/metadata/12345

Finding Your Plex ID (Rating Key)

From app.plex.tv: When you click on a movie or episode in the Plex web app, look at the URL:

https://app.plex.tv/desktop#!/server/abc123/details?key=/library/metadata/12345
                                                                    ^^^^^^^

The number after /metadata/ is your Plex ID (rating key).

From your own Plex server (e.g., plex.example.com):

https://plex.example.com/web/details?key=/library/metadata/12345
                                                        ^^^^^^^

The number after /metadata/ is your Plex ID (rating key).

You can then use:

plexclip download 12345 -o video.mp4

How It Works

Direct Downloads

For supported media, plexclip downloads the original file directly using HTTP Range requests for resume support.

HLS Transcoding

For time ranges or when direct access isn't available:

  1. Starts a transcode session with Plex Media Server
  2. Downloads HLS segments concurrently
  3. Concatenates segments using ffmpeg
  4. Verifies output with ffprobe

Requirements

  • ffmpeg and ffprobe must be installed for HLS transcoding

Configuration

Config file: ~/.config/plexclip/config.toml

[auth]
token = "your-plex-token-here"
# OR use command substitution (recommended for sensitive tokens)
token = { cmd = "pass show plex/token" }
# token = { cmd = "cat ~/.plexpass" }
# token = { cmd = "secret-tool lookup plex token" }

[[servers]]
name = "home"
url = "http://localhost:32400"
default = true

[defaults]
format = "mp4"
resolution = "1920x1080"
bitrate = 8000  # kbps
quality = 75    # 0-100

Command Substitution for Tokens

You can use command substitution to load sensitive values from external commands like password managers:

[auth]
# Execute a command to get the token
token = { cmd = "pass show plex/token" }

Examples:

  • pass: token = { cmd = "pass show plex/token" }
  • password-store: token = { cmd = "cat ~/.plexpass" }
  • secret-tool: token = { cmd = "secret-tool lookup plex token" }
  • any shell command: token = { cmd = "your-command-here" }

The command's stdout (first line, trimmed) will be used as the token. You cannot specify both token and token_cmd in the same config.

Troubleshooting

Authentication Issues

# Verify token is valid
plexclip info 12345

# If you get "Authentication required", check:
# 1. Token is correct
# 2. Server URL is reachable
# 3. Plex server allows downloads

Transcode Issues

# Ensure ffmpeg is installed
ffmpeg -version

# Try direct download if transcoding fails
plexclip download 12345 --direct

# Use debug mode to see full server response
plexclip download 12345 --debug

Development

Setup

git clone https://git.sr.ht/~jacky/plexclip
cd plexclip
cargo build

Testing

# Run all tests
cargo test

# Run with coverage
cargo tarpaulin --out Html

Code Style

# Format code
cargo fmt

# Lint
cargo clippy

CI/CD

Project uses builds.sr.ht for continuous integration and automated releases. See .builds.yml for configuration.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option. See LICENSE-APACHE or LICENSE-MIT for details.

Security

This tool downloads content you have legal access to through your Plex Media Server. Please ensure you have proper rights to any content you download.