# 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
```bash
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](https://git.sr.ht/~jacky/plexclip/refs).
## Quick Start
### 1. Configure Authentication
#### Interactive Terminal Input (Recommended)
```bash
# Interactive terminal input for token and server
plexclip auth --terminal --server http://localhost:32400
```
#### Manual Token Input
```bash
# Add your Plex server and token
plexclip auth --server http://localhost:32400 --token YOUR_PLEX_TOKEN
```
#### Help with Token Acquisition
```bash
# Get interactive help for obtaining your Plex token
plexclip auth --login
```
### 2. Download a Video
```bash
# 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
```bash
# 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
```bash
# Download and open with default player
plexclip download 12345 --open -o video.mp4
```
## Commands
### Download
Download videos from Plex Media Server:
```bash
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:
```bash
plexclip info <URL>
```
### Auth
Manage authentication:
```bash
# 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:
```bash
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:
```bash
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`
```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:
```toml
[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
```bash
# 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
```bash
# 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
```bash
git clone https://git.sr.ht/~jacky/plexclip
cd plexclip
cargo build
```
### Testing
```bash
# Run all tests
cargo test
# Run with coverage
cargo tarpaulin --out Html
```
### Code Style
```bash
# Format code
cargo fmt
# Lint
cargo clippy
```
### CI/CD
Project uses [builds.sr.ht](https://builds.sr.ht/~jacky/plexclip) for continuous integration and automated releases. See [.builds.yml](.builds.yml) for configuration.
## License
Licensed under either of Apache License, Version 2.0 or MIT license at your option. See [LICENSE-APACHE](LICENSE-APACHE) or [LICENSE-MIT](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.