README
¶
Outtake
A web app that cuts video clips, GIFs, and screenshots from your Plex libraries.
Outtake is a self-hosted web app for the media in your Plex libraries. Log in with Plex, open a title, mark where the clip starts and ends, and download a video clip, GIF, or screenshot.
Documentation: outtake.papagolabs.com
What it does
- Log in with Plex, or paste a token.
- Browse libraries, search titles, and open an item.
- Mark the start and end from live Plex playback, or type the times yourself.
- Export a video clip, GIF, or screenshot, then preview and download it.
- Keep named clip profiles for the quality, encoder preset, audio bitrate, maximum resolution, and whether HDR is kept, and optionally trim black bars on each export.
- Keep HDR in 10-bit HEVC for phones, Apple devices, and YouTube, or tone-map it to SDR for everywhere else.
 |
 |
 |
 |
Quick start
Outtake needs a Plex Media Server it can reach and read access to the media files Plex plays. The image ships FFmpeg. Save this as docker-compose.yaml:
services:
outtake:
image: ghcr.io/papagolabs/outtake:latest
container_name: outtake
ports:
- "8080:8080"
volumes:
- outtake-data:/data
- ${OUTTAKE_MEDIA_PATH:-/path/to/your/media}:/media:ro
environment:
OUTTAKE_LOG_LEVEL: info
OUTTAKE_LISTEN_ADDR: 0.0.0.0:8080
OUTTAKE_PUBLIC_BASE_URL: ${OUTTAKE_PUBLIC_BASE_URL:-http://localhost:8080}
OUTTAKE_PLEX_MEDIA_ROOT: ${OUTTAKE_PLEX_MEDIA_ROOT:-}
OUTTAKE_LOCAL_MEDIA_ROOT: ${OUTTAKE_LOCAL_MEDIA_ROOT:-/media}
restart: unless-stopped
volumes:
outtake-data:
Point OUTTAKE_MEDIA_PATH at the directory that holds the files Plex plays, then start it:
export OUTTAKE_MEDIA_PATH=/path/to/your/media
docker compose up -d
Open http://localhost:8080 and choose Login With Plex. The first Plex account to log in owns Outtake.
Documentation
- Setup: installing Outtake and configuring it
- Install: Docker Compose, Docker, a build from source, or a host binary
- Configuration: every
OUTTAKE_variable, media paths, and host names - Storage and Databases: files, S3, SQLite, and Postgres
- Kubernetes: example manifests and an example Helm chart
- Upgrading: what changes in each version, and what to do before and after updating
- Guide: using Outtake once it is running
- Logging In and Servers: the owner account and the server Outtake uses
- Making Clips: marking a selection, exporting it, and managing clips
- Profiles and Settings: quality, size, HDR, previews, and appearance
- HDR and Playback: when clips keep HDR and what your browser plays
- Troubleshooting: fixes for common problems and how to report one
- CLI Reference: every command and flag
The site's source is under docs/.
License
Outtake is licensed under the GNU Affero General Public License v3.0.
Contributing
Development commands and repo conventions live in AGENTS.md.
Documentation
¶
Overview ¶
Package main hosts the outtake command, a web-based media clipper for Plex libraries. It enables users to create video clips, GIFs, and screenshots from their Plex media server through an intuitive HTMX-powered web interface.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
api
Package api names the wire types handlers still import.
|
Package api names the wire types handlers still import. |
|
app
Package app provides the application composition root and lifecycle management.
|
Package app provides the application composition root and lifecycle management. |
|
app/health
Package health provides health check logic for the outtake server.
|
Package health provides health check logic for the outtake server. |
|
clip
Package clip holds the clip record, the render that produces it, and the encode policy that shapes both.
|
Package clip holds the clip record, the render that produces it, and the encode policy that shapes both. |
|
clip/catalog
Package catalog holds the clip list query and the rules that filter and order jobs for it.
|
Package catalog holds the clip list query and the rules that filter and order jobs for it. |
|
clip/playback
Package playback holds the settings for watching clips inside the app, such as the width previews are rendered at.
|
Package playback holds the settings for watching clips inside the app, such as the width previews are rendered at. |
|
clip/preview
Package preview renders the short low quality segments a user watches before exporting a clip.
|
Package preview renders the short low quality segments a user watches before exporting a clip. |
|
clip/profile
Package profile is the settings subdomain that owns the clip encode profiles: resolving a clip's profile to its encode settings, the profiles stored in clip_profiles, built-ins and a user's own alike, and the service that reads and edits them.
|
Package profile is the settings subdomain that owns the clip encode profiles: resolving a clip's profile to its encode settings, the profiles stored in clip_profiles, built-ins and a user's own alike, and the service that reads and edits them. |
|
clip/queue
Package queue provides a simple job queue for processing media jobs.
|
Package queue provides a simple job queue for processing media jobs. |
|
clip/quota
Package quota bounds what a member may render: how many renders run at once, how many start in a rolling week, how much storage their clips take, and how long one clip may be.
|
Package quota bounds what a member may render: how many renders run at once, how many start in a rolling week, how much storage their clips take, and how long one clip may be. |
|
cmd
Package cmd provides the outtake CLI commands.
|
Package cmd provides the outtake CLI commands. |
|
cmd/health
Package health provides the health check CLI command.
|
Package health provides the health check CLI command. |
|
cmd/owner
Package owner provides the CLI commands that manage which Plex account owns the installation.
|
Package owner provides the CLI commands that manage which Plex account owns the installation. |
|
cmd/server
Package server provides server-related CLI commands.
|
Package server provides server-related CLI commands. |
|
cmd/version
Package version provides the CLI command for displaying application version information.
|
Package version provides the CLI command for displaying application version information. |
|
failure
Package failure describes what went wrong for the person who hit it: a plain message picked from the domain packages' sentinels and typed errors, and, when the message is not enough, details to report an issue with.
|
Package failure describes what went wrong for the person who hit it: a plain message picked from the domain packages' sentinels and typed errors, and, when the message is not enough, details to report an issue with. |
|
ffmpeg
Package ffmpeg drives the ffmpeg and ffprobe processes that turn a source into a clip, a GIF, a still, or a preview.
|
Package ffmpeg drives the ffmpeg and ffprobe processes that turn a source into a clip, a GIF, a still, or a preview. |
|
ffmpeg/crop
Package crop parses ffmpeg cropdetect rectangles.
|
Package crop parses ffmpeg cropdetect rectangles. |
|
ffmpeg/ffmpegtest
Package ffmpegtest provides fake ffmpeg and ffprobe binaries for tests.
|
Package ffmpegtest provides fake ffmpeg and ffprobe binaries for tests. |
|
ffmpeg/probe
Package probe reads what a source file actually is, using ffprobe.
|
Package probe reads what a source file actually is, using ffprobe. |
|
ffmpeg/progress
Package progress reports ffmpeg encode completion from stderr.
|
Package progress reports ffmpeg encode completion from stderr. |
|
ffmpeg/tonemap
Package tonemap builds the ffmpeg filter chain that maps an HDR source down to Rec.709 so a browser renders it the way it was graded.
|
Package tonemap builds the ffmpeg filter chain that maps an HDR source down to Rec.709 so a browser renders it the way it was graded. |
|
logging
Package logging provides structured logging for outtake.
|
Package logging provides structured logging for outtake. |
|
metadata
Package metadata provides application version and build information.
|
Package metadata provides application version and build information. |
|
plex
Package plex provides a client for the Plex Media Server API.
|
Package plex provides a client for the Plex Media Server API. |
|
plex/decode/key
Package key resolves Plex metadata identifiers from Plex metadata paths.
|
Package key resolves Plex metadata identifiers from Plex metadata paths. |
|
plex/decode/plextv
Package plextv decodes plex.tv XML MediaContainer envelopes.
|
Package plextv decodes plex.tv XML MediaContainer envelopes. |
|
plex/decode/pms
Package pms decodes documented Plex Media Server JSON envelopes.
|
Package pms decodes documented Plex Media Server JSON envelopes. |
|
plex/identity
Package identity owns who the caller is and which Plex server answers for them.
|
Package identity owns who the caller is and which Plex server answers for them. |
|
plex/library
Package library holds the media library domain that sits behind the HTTP adapter.
|
Package library holds the media library domain that sits behind the HTTP adapter. |
|
plex/session
Package session monitors live playback sessions on a Plex Media Server.
|
Package session monitors live playback sessions on a Plex Media Server. |
|
settings/config
Package config is the settings subdomain that loads the application configuration, from the config file, the environment, and the defaults it seeds when neither carries a value.
|
Package config is the settings subdomain that loads the application configuration, from the config file, the environment, and the defaults it seeds when neither carries a value. |
|
settings/flags
Package flags defines every command-line flag the outtake CLI accepts, one file per command.
|
Package flags defines every command-line flag the outtake CLI accepts, one file per command. |
|
store/blob
Package blob provides blob storage for media files.
|
Package blob provides blob storage for media files. |
|
store/database
Package database provides SQLite and Postgres-protocol access for outtake.
|
Package database provides SQLite and Postgres-protocol access for outtake. |
|
timecode
Package timecode formats and parses FFmpeg time durations.
|
Package timecode formats and parses FFmpeg time durations. |
|
web
Package web assembles Outtake's inbound HTTP layer.
|
Package web assembles Outtake's inbound HTTP layer. |
|
web/assets
Package assets embeds the static files the web app serves under /assets, and names each one by a URL that carries a hash of its contents, so a browser can cache it for as long as the file is unchanged.
|
Package assets embeds the static files the web app serves under /assets, and names each one by a URL that carries a hash of its contents, so a browser can cache it for as long as the file is unchanged. |
|
web/exportform
Package exportform decodes the New export form from a request or a query, for the media item page and the redirect a finished preview comes back through.
|
Package exportform decodes the New export form from a request or a query, for the media item page and the redirect a finished preview comes back through. |
|
web/handlers/auth
Package auth serves the Plex sign-in routes.
|
Package auth serves the Plex sign-in routes. |
|
web/handlers/clip
Package clip serves the clip routes: creating a clip, editing one, canceling one, deleting one, listing them, and handing a finished file back.
|
Package clip serves the clip routes: creating a clip, editing one, canceling one, deleting one, listing them, and handing a finished file back. |
|
web/handlers/health
Package health serves the liveness endpoint.
|
Package health serves the liveness endpoint. |
|
web/handlers/home
Package home serves the dashboard, login, playback, and appearance pages.
|
Package home serves the dashboard, login, playback, and appearance pages. |
|
web/handlers/library
Package library serves the media library pages: the browse grid, a media item, and the library navigation.
|
Package library serves the media library pages: the browse grid, a media item, and the library navigation. |
|
web/handlers/library/media
Package media serves the routes that read Plex media directly: the live session lookup and the media search.
|
Package media serves the routes that read Plex media directly: the live session lookup and the media search. |
|
web/handlers/library/thumb
Package thumb serves the Plex thumbnail cache proxy, which answers a poster request from the local cache and otherwise fetches it from the selected server.
|
Package thumb serves the Plex thumbnail cache proxy, which answers a poster request from the local cache and otherwise fetches it from the selected server. |
|
web/handlers/live
Package live serves the event stream that keeps a page current.
|
Package live serves the event stream that keeps a page current. |
|
web/handlers/preview
Package preview serves the segment previews the export form shows: rendering one, reporting its progress, canceling it, and serving the file a finished render published.
|
Package preview serves the segment previews the export form shows: rendering one, reporting its progress, canceling it, and serving the file a finished render published. |
|
web/handlers/profile
Package profile serves the clip profile settings page and the edits posted to it.
|
Package profile serves the clip profile settings page and the edits posted to it. |
|
web/handlers/server
Package server serves the Plex server list and the selection posted to it.
|
Package server serves the Plex server list and the selection posted to it. |
|
web/handlers/storage
Package storage serves the storage settings page and its clear actions.
|
Package storage serves the storage settings page and its clear actions. |
|
web/handlers/users
Package users serves the users settings page, where the owner and admins approve accounts, change roles, remove users, and set render limits, and the page an account waits on until it is approved.
|
Package users serves the users settings page, where the owner and admins approve accounts, change roles, remove users, and set render limits, and the page an account waits on until it is approved. |
|
web/middleware
Package middleware provides HTTP middleware for the outtake API.
|
Package middleware provides HTTP middleware for the outtake API. |
|
web/middleware/middlewaretest
Package middlewaretest lets handler tests make requests as a signed-in caller without a session, recording the caller the way the auth guard does.
|
Package middlewaretest lets handler tests make requests as a signed-in caller without a session, recording the caller the way the auth guard does. |
|
web/respond
Package respond holds how a handler answers a request.
|
Package respond holds how a handler answers a request. |
|
web/respond/respondtest
Package respondtest lets handler tests see the failure a handler left in the session for the next page, which a redirect carries there instead of the address.
|
Package respondtest lets handler tests see the failure a handler left in the session for the next page, which a redirect carries there instead of the address. |
|
web/routes
Package routes holds the vocabulary of the web surface: the paths it serves, the query parameters it reads, and how a link into it is built.
|
Package routes holds the vocabulary of the web surface: the paths it serves, the query parameters it reads, and how a link into it is built. |
|
web/theme
Package theme catalogs selectable UI color palettes.
|
Package theme catalogs selectable UI color palettes. |
|
web/utils
Package utils provides shared helpers for the Outtake web layer.
|
Package utils provides shared helpers for the Outtake web layer. |
|
web/view
Package view holds shared HTML view models for Outtake pages and widgets.
|
Package view holds shared HTML view models for Outtake pages and widgets. |
|
tools
|
|
|
docgen
command
Command docgen writes the outtake CLI reference as Hugo pages.
|
Command docgen writes the outtake CLI reference as Hugo pages. |
Click to show internal directories.
Click to hide internal directories.