~jacky/plexclip - A CLI tool for downloading parts of a video from a Plex server (clipping) - sourcehut git

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

# Download with subsecond precision (1.5 minutes)
plexclip download 12345 --start 0 --duration 1.5m -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.sss, seconds, or units like "30s", "1.5m", "2h")
  -e, --end <END>          End time (HH:MM:SS.sss, seconds, or units like "30s", "1.5m", "2h")
  -d, --duration <TIME>     Duration to download (seconds, HH:MM:SS.sss, or units like "30s", "1.5m", "2h")
      --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:

#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:

#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:

Starts a transcode session with Plex Media Server
Downloads HLS segments concurrently
Concatenates segments using ffmpeg
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 and Legality

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.