PlexCleaner
Utility to optimize media files for Direct Play in Plex, Emby, Jellyfin, etc.
Build and Distribution
- Source Code: GitHub - Full source code, issues, and CI/CD pipelines.
- Binary Releases: GitHub Releases - Pre-compiled executables for Windows, Linux, and macOS.
- Docker Images: Docker Hub - Container images with all tools pre-installed.
Build Status
Releases
Release Notes
Version: 3.23:
Summary:
- Added a minimum version for every media tool, checked at startup, such as FFmpeg 8.0 and HandBrake 1.10.0.
- Renamed the Docker image test script to
/Test/test.sh and the version script to /PlexCleaner/version.sh.
- Fixed a verify false positive that reported healthy video with an irregular frame cadence as non-monotonic DTS.
- Stopped re-encoding to repair a non-monotonic DTS that only appears after decode, since the re-encode drops frames.
- An exception in one file fails only that file instead of ending the run.
See Release History for complete release notes and older versions.
Getting Started
Get started with PlexCleaner in three easy steps using Docker (recommended):
⚠️ Important: PlexCleaner modifies media files in place. Always maintain backups of your media library before processing. Consider testing on sample files first.
ℹ️ Note: Replace /data/media with your actual host media directory path. All examples map the host directory to /media inside the container.
ℹ️ Note: The examples run as the nonroot user and users group that own your media. Files PlexCleaner writes then stay readable by the rest of your stack. Set USER_NONROOT_ID and USERS_GROUP_ID to your own numeric IDs, and see Docker Run Examples to prepare the media directory.
# Replace with your own IDs, from `id -u nonroot` and `getent group users | cut -d: -f3`
USER_NONROOT_ID=1001
USERS_GROUP_ID=100
# 1. Create a default settings file
docker run --rm --user "${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?}" --volume /data/media:/media:rw docker.io/ptr727/plexcleaner \
/PlexCleaner/PlexCleaner defaultsettings --settingsfile /media/PlexCleaner/PlexCleaner.json
# 2. Edit /data/media/PlexCleaner/PlexCleaner.json to suit your needs
# 3. Process your media files
docker run --rm --user "${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?}" --volume /data/media:/media:rw docker.io/ptr727/plexcleaner \
/PlexCleaner/PlexCleaner --logfile /media/PlexCleaner/PlexCleaner.log \
process --settingsfile /media/PlexCleaner/PlexCleaner.json \
--mediafiles /media/Movies --mediafiles /media/Series
See Installation for detailed setup instructions and other platforms.
Table of Contents
Overview
ℹ️ TL;DR: Direct Play means your media server (Plex/Emby/Jellyfin) sends the file directly to your player without transcoding on the server or the client. This saves server CPU, reduces power consumption, preserves quality, and enables playback on low-power devices. The objective of PlexCleaner is to modify media content such that it will always Direct Play in Plex, Emby, Jellyfin, etc.
Common examples of issues resolved by the process command:
Container & Codec Issues:
- Non-MKV containers → Re-multiplex to MKV (player compatibility).
- MPEG-2 video → Re-encode to H.264 (licensing prevents hardware decoding).
- MPEG-4 or VC-1 video → Re-encode to H.264 (playback issues).
- H.264
Constrained Baseline@30 → Re-encode to H.264 High@40 (playback issues).
- Vorbis or WMAPro audio → Re-encode to AC3 (platform compatibility).
Track Management:
- Missing language tags → Set language for unknown tracks (enables automatic selection).
- Invalid or unmappable IETF/BCP-47 language tags → Set to a valid tag in place.
- Duplicate audio/subtitle tracks → Remove duplicates, keep best quality.
- VOBsub subtitles without
MuxingMode → Re-multiplex to set correct attribute (prevents hangs).
Video Quality:
- Interlaced video → Deinterlace using HandBrake
--comb-detect --decomb.
- Embedded closed captions (EIA-608/CTA-708) → Remove from video streams (can’t be managed by player).
- Dolby Vision profile 5 → Warn when not profile 7 (DV/HDR10 compatibility).
Performance & Integrity:
- Corrupt media streams → Verify integrity and attempt automatic repair.
- Non-monotonic DTS timestamps → Losslessly rewrite the packet timestamps using
setts.
- Matroska files that fail player Direct Play despite passing tool checks → Detect an unusable seek index (SeekHead/Cues) and re-multiplex.
- High bitrate content → Warn when exceeding network capacity (WiFi/100Mbps Ethernet).
See the process command for detailed workflow and the Common Configuration Examples for quick setup examples.
PlexCleaner is optimized for processing large media libraries efficiently. Key performance features and tips:
⚡ Performance Tips:
- Large libraries: Use
--parallel to process multiple files concurrently.
- Testing: Combine
--testsnippets and --quickscan for faster test iterations.
- Network storage: Process files locally when possible to avoid network bottlenecks.
- Docker logging: Configure log rotation to prevent large log files.
- Thread count: Default is half of CPU cores (max 4); adjust with
--threadcount if needed.
Sidecar Files:
- To improve processing performance of large media collections, the media file attributes and processing state is cached in sidecar files. (
filename.mkv -> filename.PlexCleaner)
- Sidecar files allow re-processing of the same files to be very fast as the state will be read from the sidecar vs. re-computed from the media file.
- The sidecar maintains a hash of small parts of the media file (timestamps are unreliable), and the media file will be reprocessed when a change in the media file is detected.
Processing Operations:
- Re-multiplexing is an IO intensive operation and re-encoding is a CPU intensive operation.
- Parallel processing, using the
--parallel option, is useful when a single instance of FFmpeg or HandBrake does not saturate all the available CPU resources.
- Processing can be interrupted using
Ctrl-Break, if using sidecar files restarting will skip previously verified files.
Temporary Files:
- Processing writes tool output beside the media file, under a
.tmp extension numbered per step. (filename.mkv -> filename.tmp4)
- The
.tmp* extensions are reserved for PlexCleaner, so do not keep your own files under them in a media folder.
- A file found under a temporary name, such as one left behind by an interrupted run, is overwritten.
- A temporary file is deleted when its tool fails or the step no longer needs it, or moved to its target name on success.
- A temporary file only ever holds tool output, never the media itself, so a leftover temporary file is safe to delete.
- With
DeleteUnwantedExtensions enabled, the process command deletes a leftover temporary file like any other non-MKV file.
- The
monitor command ignores changes to temporary files.
Docker Considerations:
- Processing very large media collections on docker may result in a very large docker log file, set appropriate docker logging options.
Installation
Choose an installation method based on your platform and requirements:
-
Docker (Recommended): Easiest and most up-to-date option.
- ✅ All tools pre-installed and automatically updated.
- ✅ Consistent experience across platforms.
- ✅ Supports
linux/amd64 and linux/arm64 architectures.
- Best for: Linux, NAS devices, servers, cross-platform deployments.
-
Windows: Native installation with automatic tool updates.
- ✅ Automatic tool downloads and updates via
checkfornewtools command.
- ✅ Or use
winget for system-wide tool installation.
- Best for: Windows desktops and servers.
-
Linux: Manual installation.
- ⚠️ Requires manual tool installation via package manager.
- ⚠️ No automatic tool updates.
- Best for: Users who prefer native binaries over Docker.
-
macOS: Limited support.
- ⚠️ Binaries built but not tested in CI.
- ⚠️ Manual tool installation required.
PlexCleaner exits with an error at startup when an installed tool is older than its minimum version. The minimum versions are:
| Tool |
Minimum version |
| FFmpeg and FFprobe |
8.0 |
| HandBrake |
1.10.0 |
| MediaInfo |
25.07 |
| MKVToolNix |
94.0 |
| 7-Zip |
25.01 |
A version with a release prefix, a HandBrake nightly (by branch or build date), or an FFmpeg build named by date is compared by that. A version string that cannot be compared is accepted with a warning. The Docker image and the Windows automatic download provide current tools. A winget, manual, Linux, or macOS install must provide versions that meet the minimums.
Docker
- Builds are published on Docker Hub.
- See the Docker README for current distribution and media tool versions.
ptr727/plexcleaner:latest is based on Ubuntu (ubuntu:rolling) built from the main branch.ptr727/plexcleaner:develop is based on Ubuntu (ubuntu:rolling) built from the develop branch.- Docker images and GitHub Releases for both branches are published on a weekly schedule (and on demand), each refreshed with the latest upstream and base-image updates. Pull requests are smoke-tested only and do not publish.
- The container has all the prerequisite 3rd party tools pre-installed.
Path Mapping Convention: All examples use /data/media as the host path mapped to /media inside the container. Replace /data/media with your actual host media location.
Docker Compose (Recommended for Monitor Mode)
For continuous monitoring of media folders, use Docker Compose.
services:
plexcleaner:
image: docker.io/ptr727/plexcleaner:latest # Use :develop for pre-release builds
container_name: PlexCleaner
restart: unless-stopped
stop_grace_period: 30s # Allow time to finish the current file and log the summary on stop
user: ${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?} # Set in .env to your own IDs, e.g. USER_NONROOT_ID=1001 and USERS_GROUP_ID=100
command:
- /PlexCleaner/PlexCleaner
- monitor # Monitor command
- --settingsfile=/media/PlexCleaner/PlexCleaner.json # Path inside container
- --logfile=/media/PlexCleaner/PlexCleaner.log # Path inside container
- --preprocess # Process all existing files on startup
- --mediafiles=/media/Series # Add multiple --mediafiles for each folder to monitor
- --mediafiles=/media/Movies # Paths inside container (mapped from host volumes)
environment:
- TZ=America/Los_Angeles # Set your timezone
volumes:
- /data/media:/media # Map host path /data/media to container /media (read/write)
On stop (docker stop, or Compose shutdown), PlexCleaner handles the termination signal, stops processing gracefully, and logs the run summary and exit code before exiting. Because it aborts the in-flight file rather than killing it mid-write, allow enough grace for a long re-encode to unwind: set stop_grace_period (Compose) or --stop-timeout / docker stop --time 30 (Docker run). Without enough grace the container is force-killed (SIGKILL) and the summary is lost.
Docker Run Examples
For a simple one-time process operation, see the Getting Started example.
Setup Permissions:
PlexCleaner runs as a non-root user, so the media directory must be owned by and writable for that user and group. Prepare it once:
# Create the nonroot system user in the users group, with the Debian or Ubuntu adduser
sudo adduser --no-create-home --disabled-password --system --ingroup users nonroot
# Give nonroot:users ownership, with group read and write
sudo chown -R nonroot:users /data/media
sudo chmod -R ug=rwX,o=rX /data/media
# New files keep the users group
sudo find /data/media -type d -exec chmod g+s {} +
# New files stay group writable, which needs the acl package and a filesystem with ACL support
sudo find /data/media -type d -exec setfacl -m d:g:users:rwx {} +
# The numeric IDs the examples use as USER_NONROOT_ID and USERS_GROUP_ID
id -u nonroot
getent group users | cut -d: -f3
Interactive Shell Access:
# Replace with your own IDs, from `id -u nonroot` and `getent group users | cut -d: -f3`
USER_NONROOT_ID=1001
USERS_GROUP_ID=100
# Replace /data/media with your actual media directory
docker run \
-it --rm --pull always \
--name PlexCleaner \
--user "${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?}" \
--volume /data/media:/media:rw \
docker.io/ptr727/plexcleaner \
/bin/bash
# Inside the container, run PlexCleaner commands (see Quick Start)
exit
Monitor Command in Screen Session:
# Start or attach to screen session
screen
# Or: screen -rd
# Replace with your own IDs, from `id -u nonroot` and `getent group users | cut -d: -f3`
USER_NONROOT_ID=1001
USERS_GROUP_ID=100
# Run monitor (adjust paths as needed)
docker run -it --rm --pull always \
--log-driver json-file --log-opt max-size=10m \
--name PlexCleaner --env TZ=America/Los_Angeles \
--user "${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?}" \
--volume /data/media:/media:rw \
docker.io/ptr727/plexcleaner \
/PlexCleaner/PlexCleaner --logfile /media/PlexCleaner/PlexCleaner.log --loglevel Warning --logelevate \
monitor --settingsfile /media/PlexCleaner/PlexCleaner.json --parallel \
--mediafiles /media/Movies --mediafiles /media/Series
Process Command:
For one-time processing, see the Getting Started example or use similar syntax as above, replacing monitor with process.
Windows
Prerequisites:
- For pre-compiled binaries: Install .NET Runtime (smaller, runtime only).
- For compiling from source: Install .NET SDK (includes build tools).
Installation Steps:
-
Download PlexCleaner and extract the pre-compiled binaries.
-
Create a default JSON settings file using the defaultsettings command:
PlexCleaner defaultsettings --settingsfile PlexCleaner.json- Modify the settings to suit your needs.
-
Install the required 3rd party tools (choose one method):
Option A: Automatic download (Recommended)
PlexCleaner checkfornewtools --settingsfile PlexCleaner.json- The default
Tools folder will be created in the same folder as the PlexCleaner binary file.
- The tool version information will be stored in
Tools\Tools.json.
- Keep the 3rd party tools updated by periodically running the
checkfornewtools command, or update tools on every run by setting ToolsOptions:AutoUpdate to true.
Option B: System-wide installation via winget
- Run from an elevated shell e.g. using
gsudo, else symlinks will not be created.
winget install --id=Gyan.FFmpeg --exactwinget install --id=MediaArea.MediaInfo --exactwinget install --id=HandBrake.HandBrake.CLI --exactwinget install --id=MoritzBunkus.MKVToolNix --exact --installer-type portable- Set
ToolsOptions:UseSystem to true and ToolsOptions:AutoUpdate to false.
Option C: Manual download
- FfMpeg Full, e.g.
ffmpeg-9.0.2-full_build.7z: \Tools\FfMpeg
- HandBrake CLI x64, e.g.
HandBrakeCLI-1.6.1-win-x86_64.zip: \Tools\HandBrake
- MediaInfo CLI x64, e.g.
MediaInfo_CLI_23.07_Windows_x64.zip: \Tools\MediaInfo
- MkvToolNix Portable x64, e.g.
mkvtoolnix-64-bit-79.0.7z: \Tools\MkvToolNix
- 7-Zip Extra, e.g.
7z2301-extra.7z: \Tools\SevenZip
- Set
ToolsOptions:UseSystem to false and ToolsOptions:AutoUpdate to false.
Linux
- Automatic downloading of Linux 3rd party tools are not supported, consider using the Docker build instead.
- Manually install the 3rd party tools, e.g. following steps similar to the Docker file commands.
- Download PlexCleaner and extract the pre-compiled binaries matching your platform.
- Or compile from code using the .NET SDK.
- Create a default JSON settings file using the
defaultsettings command:
./PlexCleaner defaultsettings --settingsfile PlexCleaner.json- Modify the settings to suit your needs.
macOS
- macOS x64 and Arm64 binaries are built as part of Releases, but are not tested during CI.
AOT
Ahead-of-time compiled self-contained binaries do not require any .NET runtime components to be installed.
AOT builds are platform specific, require a platform native compiler, and are created using dotnet publish.
ℹ️ Note: AOT binaries are not published in CI/CD due to being platform specific, and cross compilation of AOT binaries are not supported.
# Install .NET SDK and native code compiler
apt install dotnet-sdk-10.0 clang zlib1g-dev
# Clone repository (main or develop branch)
git clone -b develop https://github.com/ptr727/PlexCleaner.git ./PlexCleanerAOT
cd ./PlexCleanerAOT
# Publish standalone release build executable
dotnet publish ./PlexCleaner/PlexCleaner.csproj \
--output ./PublishAOT \
--configuration release \
-property:PublishAot=true
ℹ️ Note: The custom plugin command loads assemblies at runtime and is not available in AOT builds; use a standard (JIT) build, which is what the published binaries and Docker images use.
Configuration
Default Settings
Create a default JSON configuration file by running:
PlexCleaner defaultsettings --settingsfile PlexCleaner.json
⚠️ Important: The default settings file must be edited to match your requirements before processing media files.
Required Changes:
- Verify language settings:
ProcessOptions.DefaultLanguageProcessOptions:KeepLanguagesProcessOptions.SetUnknownLanguageProcessOptions.RemoveUnwantedLanguageTracks
- Verify codec settings:
ProcessOptions.ReEncodeVideoProcessOptions.ReEncodeAudioFormats
- Verify encoding settings:
ConvertOptions.FfMpegOptionsConvertOptions.HandBrakeOptions
- Verify processing settings:
ProcessOptions.VerifyProcessOptions.ReMuxProcessOptions.ReEncodeProcessOptions.DeInterlaceProcessOptions.DeleteUnwantedExtensionsProcessOptions.RemoveTagsProcessOptions.RemoveDuplicateTracksProcessOptions.RemoveClosedCaptions
- Verify verification settings:
VerifyOptions.AutoRepairVerifyOptions.DeleteInvalidFilesVerifyOptions.RegisterInvalidFiles
Refer to the commented default JSON settings file for detailed configuration options and explanations.
Common Configuration Examples
Quick configuration examples for common use cases. Edit your PlexCleaner.json file:
Keep Only English and Spanish Audio and Subtitles:
"ProcessOptions": {
"KeepLanguages": ["en", "es"],
"RemoveUnwantedLanguageTracks": true
}
Re-encode MPEG-2 and VC1 Video to H.264:
"ProcessOptions": {
"ReEncode": true,
"ReEncodeVideo": [
{
"Format": "mpeg2video"
},
{
"Format": "vc1"
}
]
},
"ConvertOptions": {
"FfMpegOptions": {
"Video": "libx264 -crf 22 -preset medium"
}
}
Re-encode Vorbis and WMAPro Audio to AC3:
"ProcessOptions": {
"ReEncode": true
},
"ConvertOptions": {
"ReEncodeAudioFormats": ["vorbis", "wmapro"],
"FfMpegOptions": {
"Audio": "ac3"
}
}
Remove Duplicate Audio Tracks and Keep the Best Quality:
"ProcessOptions": {
"RemoveDuplicateTracks": true,
"PreferredAudioFormats": [
"ac-3",
"dts-hd high resolution audio",
"dts-hd master audio",
"dts",
"e-ac-3",
"truehd atmos",
"truehd"
]
}
Verify Media Integrity and Auto-Repair:
"ProcessOptions": {
"Verify": true,
"AutoRepair": true,
"DeleteInvalidFiles": false,
"RegisterInvalidFiles": true
}
IETF Language Matching
ℹ️ TL;DR: Language tag matching supports IETF / RFC 5646 / BCP 47 tag formats as implemented by MkvMerge.
Common Use Cases:
- Keep only English: Set
ProcessOptions:KeepLanguages to ["en"].
- Keep English and Spanish: Set
ProcessOptions:KeepLanguages to ["en", "es"].
- Keep all Portuguese variants: Use
"pt" to match pt, pt-BR (Brazilian), pt-PT (European), etc.
- Keep only Brazilian Portuguese: Use
"pt-BR" to match specifically Brazilian Portuguese.
- Set IETF Language Tags if not present: Set
ProcessOptions.SetIetfLanguageTags to true.
Refer to Docs/LanguageMatching.md for technical details on language tag matching, including examples, normalization, and configuration options.
EIA-608 and CTA-708 Closed Captions
ℹ️ TL;DR: Closed captions (CC) are subtitles embedded in the video stream (not separate tracks). They can cause issues with some players that always display them or cannot disable them. PlexCleaner can detect and remove them using the RemoveClosedCaptions option. Removal is supported for H.264, H.265/HEVC, and MPEG-2 video (HDR10 and HDR10+ HEVC content is skipped to avoid stripping HDR metadata).
Refer to Docs/ClosedCaptions.md for technical details on detection and removal methods.
Custom FFmpeg and Handbrake Encoding Settings
ℹ️ Note: The default encoding settings work well for most users and provide good compatibility with Plex/Emby/Jellyfin. Only customize these settings if you have specific requirements (e.g., hardware encoding, different quality targets, or specific codec preferences).
Refer to Docs/CustomOptions.md for hardware acceleration setup, encoder options, and real-world examples.
Usage
Common Commands Quick Reference
| Command |
Purpose |
When to Use |
defaultsettings |
Create default configuration file |
First time setup |
process |
Batch process media files |
One-time processing of media library |
monitor |
Watch folders and auto-process changes |
Continuous monitoring of active media folders |
verify |
Verify media integrity without processing |
Test media files or check for corruption |
remux |
Re-multiplex to MKV without re-encoding |
Fix container issues, faster than full processing |
reencode |
Re-encode video/audio tracks |
Fix codec compatibility issues |
deinterlace |
Remove interlacing artifacts |
Fix interlaced video playback issues |
removeclosedcaptions |
Remove embedded closed captions |
Remove unwanted CC from video streams |
checkfornewtools |
Download/update media tools (Windows only) |
Keep tools up-to-date |
See detailed command documentation below for all options and usage examples.
Use the PlexCleaner --help commandline option to get a list of commands and options.
To get help for a specific command run PlexCleaner <command> --help.
> PlexCleaner --help
Description:
Utility to optimize media files for Direct Play in Plex, Emby, Jellyfin, etc.
Usage:
PlexCleaner [command] [options]
Options:
--loglevel <level> Log level: Verbose, Debug, Information, Warning, Error, Fatal [default: Information]
--logfile <filepath> Path to log file
--logclear <boolean> Clear the log file before writing (default appends)
--logelevate <boolean> Raise a file's log level to Information after a warning or error
--logappend <boolean> (Deprecated) Appending is now the default, use --logclear to clear
--logwarning <boolean> (Deprecated) Use --loglevel Warning (add --logelevate for per-file elevation)
--debug <boolean> Wait for debugger to attach
-?, -h, --help Show help and usage information
--version Show version information
Commands:
defaultsettings Create default JSON settings file
checkfornewtools Check for and download new tool versions
process Process media files
monitor Monitor file changes and process changed files
verify Verify media container and stream integrity
remux Conditionally re-multiplex media files
reencode Conditionally re-encode media files
deinterlace Conditionally de-interlace media files
removesubtitles Remove all subtitle tracks
removeclosedcaptions Remove all closed caption tracks
createsidecar Create new sidecar files
updatesidecar Create or update sidecar files
getsidecarinfo Print media sidecar information
getmediainfo Print media file information
gettoolinfo Print media tool information
gettagmap Print media tool attribute mappings
testmediainfo Test parsing media tool information
getversioninfo Print application and media tool version information
createschema Create JSON settings schema file
custom Process media files using a custom plugin assembly
Global Options
Global options apply to all commands:
--loglevel:
- Minimum log level:
Verbose, Debug, Information (default), Warning, Error, or Fatal.
--logfile:
- Path to the log file. The file appends by default and rolls to a numbered file (
<name>_001.<ext>) when it reaches 1 GiB, retaining the most recent 31 files and deleting older ones.
--logclear:
- Clear the log file before writing, default appends to the existing log file.
--logelevate:
- Raise a file’s log level back to
Information after it logs a warning or error, so the full context of a problem file is shown even at a higher --loglevel.
--logwarning:
- (Deprecated, will be removed.) Equivalent to
--loglevel Warning; add --logelevate to restore the previous per-file elevation behavior.
--logappend:
- (Deprecated, will be removed.) Appending is now the default; use
--logclear to clear the log file.
--debug:
- Launch and wait for a debugger to attach.
Process Command
> PlexCleaner process --help
Description:
Process media files
Usage:
PlexCleaner process [options]
Options:
--settingsfile <filepath> (REQUIRED) Path to settings file
--mediafiles <filepath> (REQUIRED) Path to media file or folder
--parallel <boolean> Enable parallel file processing
--threadcount <integer> Number of threads for parallel file processing
--quickscan <boolean> Scan only part of the file
--resultsfile <filepath> Path to results file
--testsnippets <boolean> Create short media file clips
-?, -h, --help Show help and usage information
--loglevel <level> Log level: Verbose, Debug, Information, Warning, Error, Fatal [default: Information]
--logfile <filepath> Path to log file
--logclear <boolean> Clear the log file before writing (default appends)
--logelevate <boolean> Raise a file's log level to Information after a warning or error
--logappend <boolean> (Deprecated) Appending is now the default, use --logclear to clear
--logwarning <boolean> (Deprecated) Use --loglevel Warning (add --logelevate for per-file elevation)
--debug <boolean> Wait for debugger to attach
The process command will process the media content using options as defined in the settings file and the optional commandline arguments.
Refer to PlexCleaner.defaults.json for complete configuration details, or see Common Configuration Examples for quick setup examples.
Processing Workflow (in order):
1. File Management:
- Delete unwanted files based on patterns.
FileIgnoreMasks, ReMuxExtensions, DeleteUnwantedExtensions
2. Container Operations:
- Re-multiplex non-MKV containers to MKV format.
- Remove all tags, titles, thumbnails, cover art, and attachments. A remux or re-encode drops tags and attachments whatever this setting says.
3. Track Language and Metadata:
- Set IETF language tags and Matroska special track flags if missing.
- Set Matroska special track flags based on track titles.
- Set the default language for any track with an undefined language.
SetUnknownLanguage, DefaultLanguage
4. Track Selection:
- Remove tracks with unwanted languages.
KeepLanguages, KeepOriginalLanguage, RemoveUnwantedLanguageTracks
- Remove duplicate tracks (same type and language, keep best quality).
RemoveDuplicateTracks, PreferredAudioFormats
5. Video Processing:
- De-interlace the video stream if interlaced.
- Remove EIA-608 and CTA-708 closed captions from video stream.
- Re-encode video based on specified codecs and formats.
ReEncodeVideo, ReEncodeVideoFormats, ConvertOptions
6. Audio Processing:
- Re-encode audio based on specified formats.
ReEncode, ReEncodeAudioFormats, ConvertOptions
7. Integrity and Verification:
- Re-multiplex the media file if required to fix inconsistencies.
- Verify the media container and stream integrity.
- If verification fails, attempt automatic repair.
- If repair fails, delete or mark file to be ignored.
DeleteInvalidFiles, RegisterInvalidFiles
8. Finalization:
- Restore modified timestamp of modified files to original timestamp.
- Delete empty folders after processing.
Options:
--settingsfile: (required)
- Path to the JSON settings file.
--mediafiles: (required)
- Path to file or folder containing files to process.
- Paths with spaces should be double quoted.
- Repeat the option to include multiple files or directories, e.g.
--mediafiles path1 --mediafiles "path with space" --mediafiles file1 --mediafiles file2.
--testsnippets:
- Create shortened output snippets (30s) for any files created during processing.
- Useful when testing to speed up processing times.
- Can be combined with
--quickscan to limit file scanning operations.
- Use this option only when testing and on test files.
--parallel:
- Process multiple files concurrently.
- Useful when the system has more processing power than being utilized with serial file processing.
--threadcount:
- Concurrent file processing thread count when the
--parallel option is enabled.
- The default thread count is the largest of 1/2 number of logical processors or 4.
- Media tools internally use multiple threads.
--quickscan:
- Limits the time duration (3min) when scanning media files, applies to:
- Stream verification.
- Interlaced frame detection.
- Closed caption detection.
- Bitrate calculation.
- Improves processing times, but there is some risk of missing information present in later parts of the stream.
--resultsfile:
- Write processing results to a JSON file.
- Useful when comparing results with previous processing runs.
Example:
./PlexCleaner \
--logfile PlexCleaner.log \
process \
--settingsfile PlexCleaner.json \
--mediafiles "C:\Foo With Space\Test.mkv" \
--mediafiles D:\Media
Monitor Command
> PlexCleaner monitor --help
Description:
Monitor file changes and process changed files
Usage:
PlexCleaner monitor [options]
Options:
--settingsfile <filepath> (REQUIRED) Path to settings file
--mediafiles <filepath> (REQUIRED) Path to media file or folder
--parallel <boolean> Enable parallel file processing
--threadcount <integer> Number of threads for parallel file processing
--quickscan <boolean> Scan only part of the file
--preprocess <boolean> Pre-process all monitored folders
-?, -h, --help Show help and usage information
--loglevel <level> Log level: Verbose, Debug, Information, Warning, Error, Fatal [default: Information]
--logfile <filepath> Path to log file
--logclear <boolean> Clear the log file before writing (default appends)
--logelevate <boolean> Raise a file's log level to Information after a warning or error
--logappend <boolean> (Deprecated) Appending is now the default, use --logclear to clear
--logwarning <boolean> (Deprecated) Use --loglevel Warning (add --logelevate for per-file elevation)
--debug <boolean> Wait for debugger to attach
The monitor command will watch the specified folders for file changes, and periodically run the process command on the changed folders:
- All the referenced directories will be watched for changes, and any changes will be added to a queue to be periodically processed.
- The FileSystemWatcher used to monitor for changes may not always work as expected when changes are made via virtual or network filesystem, e.g. NFS or SMB backed volumes may not detect changes made directly to the underlying ZFS filesystem, while running directly on ZFS will work fine.
Options:
- Most of the
process command options apply.
--preprocess:
- On startup process all existing media files while watching for new changes.
Other Commands
Additional commands for specific tasks, organized by category:
Configuration:
defaultsettings:
- Create JSON configuration file using default settings.
createschema:
- Write JSON settings schema to file for validation.
Tool Management:
checkfornewtools:
- Check for new tool versions and download if newer.
- Only supported on Windows.
gettoolinfo:
- Print media tool information and versions.
File Operations:
remux:
- Conditionally re-multiplex media files.
- Re-multiplex non-MKV containers in the
ReMuxExtensions list to MKV container format.
- Same logic as used in the
process command.
reencode:
- Conditionally re-encode media files.
- Re-encode video and audio if format matches
ReEncodeVideo or ReEncodeAudioFormats to formats set in ConvertOptions.
- Same logic as used in the
process command.
deinterlace:
- De-interlace the video stream if interlaced.
- Same logic as used in the
process command.
removesubtitles:
- Remove all subtitle tracks.
- Useful when media players cannot disable subtitle output, or content is undesirable.
removeclosedcaptions:
- Remove closed captions from video stream.
- Useful when media players cannot disable EIA-608 and CTA-708 embedded in the video stream, or content is undesirable.
- Same logic as used in the
process command.
Information and Debugging:
verify:
- Verify media container and stream integrity.
- Same logic as used in the
process command.
createsidecar:
- Create new sidecar files.
- Useful to start fresh and update tool info and remove old processing state.
updatesidecar:
- Create or update sidecar files.
getversioninfo:
- Print application and tools version information.
getsidecarinfo:
- Print sidecar file information.
gettagmap:
- Print media file attribute mappings.
- Useful to show how different media tools interprets the same attributes.
getmediainfo:
- Print media file information and track details.
Runtime Metrics
PlexCleaner publishes always-on runtime metrics via System.Diagnostics.Metrics under the PlexCleaner.Process meter, so a long-running process or monitor pass can be watched live with no extra setup. Overall progress is operation-weighted: each heavy full-file operation on a file (closed-caption and interlace scans, bitrate analysis, re-encode, deinterlace, verify) counts the file’s size as work to do when it starts and as work done when it finishes. A run mixing small and large files therefore reflects the actual work completed, and because the per-file path is not fixed the total grows as operations are discovered. The meter publishes progress.ratio and eta.seconds, the work.total/work.completed byte gauges behind them, bytes.total (input size), files.total/files.inflight/files.completed, and per-tool timing histograms.
Read the meter with dotnet-counters:
- Local:
dotnet-counters monitor -p <pid> --counters PlexCleaner.Process
- Docker:
docker exec <container> counters (a bundled wrapper that runs the same command against the in-container process)
The meter is also OpenTelemetry and dotnet-monitor compatible if you want an HTTP or Prometheus surface.
Custom Plugins
The custom command runs a user-provided plugin assembly over the media files, reusing PlexCleaner’s file iteration and processing. This is useful for bespoke, targeted re-processing that the built-in commands do not cover, for example re-running a newly added or fixed verification check on a library where files are already marked as verified, without paying for a full re-verification.
A plugin is a .NET class library that references PlexCleaner.dll and implements the IProcessPlugin interface:
public interface IProcessPlugin
{
string Name { get; }
bool Initialize(IPluginHost host); // return false when incompatible, see host.PluginApiVersion
bool ProcessFile(string fileName); // called once per file, return false on failure
}
Initialize receives an IPluginHost with the deterministic PluginApiVersion, the application and OS versions, and a Serilog.ILogger to log through. ProcessFile reuses the public processing API, for example new ProcessFile(fileName) then RepairMatroskaStructure(...). Two examples are included:
MatroskaHeaderCleanup re-checks and repairs the Matroska seek-index structure on already-verified files.DtsTimestampRepair revisits files that an older version marked RepairFailed, re-verifies them, and losslessly repairs the timestamps (setts) when the non-monotonic DTS is demux-visible, clearing the flag on success; a detected DTS it cannot repair stays reported.
Notes:
- A plugin runs arbitrary code with the same privileges as PlexCleaner. Only run plugins you trust.
- The plugin type is created via reflection, so it must be a concrete class with a public parameterless constructor, and the assembly must contain exactly one
IProcessPlugin implementation.
- Many processing helpers are gated by the settings file, for example verification only runs when
ProcessOptions.Verify is enabled, so enable the relevant settings for the operation the plugin performs.
- Plugin loading uses runtime assembly loading and is not available in AOT builds; use a standard build (the published binaries and Docker images are standard builds).
- A plugin binds to a specific
PlexCleaner.dll and may need rebuilding across releases. PluginApiVersion only guards the plugin contract, but the public API a plugin calls can change in any release, so Initialize should also check host.ApplicationVersion against the PlexCleaner version the plugin was tested against (see the example).
- File processing is serial by default; if you enable
--parallel, plugin code must be thread-safe.
ProcessFile is called for every file under --mediafiles, not only Matroska files, so a plugin should filter by type (e.g. SidecarFile.IsMkvFile(fileName)) and return true to skip files it does not handle.- A plugin that modifies a file must keep the sidecar in sync or the next normal run will invalidate the saved state. Follow the example flow: confirm the file is Matroska, call
GetMediaProps() to initialize the sidecar, then modify through a ProcessFile helper such as RepairMatroskaStructure(...) that refreshes the sidecar to match the changed file.
CLI example:
dotnet PlexCleaner.dll custom \
--settingsfile /config/PlexCleaner.json \
--pluginassembly /config/plugins/MatroskaHeaderCleanup.dll \
--mediafiles /media/Movies \
--mediafiles /media/Series
Docker Compose example (one-shot):
services:
plexcleaner-custom:
image: docker.io/ptr727/plexcleaner:latest
container_name: PlexCleaner-Custom
user: ${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?} # Set in .env to your own IDs, e.g. USER_NONROOT_ID=1001 and USERS_GROUP_ID=100
command:
- /PlexCleaner/PlexCleaner
- custom
- --settingsfile=/media/PlexCleaner/PlexCleaner.json
- --pluginassembly=/media/PlexCleaner/plugins/MatroskaHeaderCleanup.dll
- --mediafiles=/media/Series
- --mediafiles=/media/Movies
environment:
- TZ=America/Los_Angeles
volumes:
- /data/media:/media # Media, config, and the plugin DLL are mounted here
Questions or Issues
For General Questions:
- Use the Discussions forum for general questions, feature requests, and sharing working configurations.
For Bug Reports:
- Ask in the Discussions forum if you are not sure if it is a bug.
- Check the Issues tracker for known problems first.
- When reporting a new bug, please include:
- PlexCleaner version (
PlexCleaner --version).
- Operating system and architecture (Windows/Linux/Docker, x64/arm64).
- Media tool versions (
PlexCleaner gettoolinfo).
- Complete command line and relevant configuration settings.
- Full log output with
--debug flag enabled.
- Sample media file information (
PlexCleaner getmediainfo --mediafiles <file>).
- Steps to reproduce the issue.
Testing
PlexCleaner includes multiple testing approaches for different scenarios:
- Unit Tests: Fast automated tests for code logic (no media files required).
- Docker Tests: Validate container functionality with sample media files.
- Regression Tests: Compare processing results across versions using real media files.
The majority of development and debugging time is spent figuring out how to deal with media file and media processing tool specifics affecting playback.
For repetitive test tasks pre-configured on-demand tests are included in VSCode tasks.json and launch.json, and VisualStudio launchSettings.json.
Several of the tests reference system local paths containing media files, so you may need to make path changes to match your environment.
Unit Testing
Unit tests validate core functionality without requiring media files. Run locally or in CI/CD pipelines.
dotnet test
Docker Testing
The test.sh script validates basic container functionality. It downloads sample files if no external media path is provided.
The test.sh test script is included in the docker build and can be used to test basic functionality from inside the container. It writes its output under /tmp/PlexCleaner-Test, so it runs as the same non-root user as the rest of the stack.
If an external media path is not specified the test will download and use the Matroska test files.
# Replace with your own IDs, from `id -u nonroot` and `getent group users | cut -d: -f3`
USER_NONROOT_ID=1001
USERS_GROUP_ID=100
docker run \
-it --rm \
--user "${USER_NONROOT_ID:?}:${USERS_GROUP_ID:?}" \
--name PlexCleaner-Test \
docker.io/ptr727/plexcleaner:latest \
/Test/test.sh
Regression Testing
Regression testing ensures consistent behavior across versions by comparing processing results on the same media files, down to the per-file processing decision.
The behavior of the tool is very dependent on the media files being tested. A reproducible process and its tooling live under RegressionTests/: a ZFS-clone harness that processes a curated collection of troublesome media through a given image tag, plus utilities that derive a machine-readable issue catalog, build a proven-equivalent reduced collection, and audit physical-error coverage. See RegressionTests/README.md for details.
Install development tools using winget (Windows):
winget install Microsoft.DotNet.SDK.10 # .NET 10 SDK
winget install Microsoft.VisualStudioCode # Visual Studio Code
winget install Microsoft.VisualStudio.Community # Visual Studio
Update .NET development tools:
dotnet tool restore # Restore tools from manifest
dotnet tool update --all # Update all .NET tools
dotnet husky install # Reinstall git hooks
dotnet outdated --upgrade:prompt # Interactive dependency updates
Feature Ideas
Have a feature request or idea? Please check GitHub Discussions and Issues first to see if it’s already been proposed. If not, feel free to start a new discussion!
Some ideas being considered:
- Cleanup chapters (e.g. chapter markers that exceed media play time).
- Cleanup NFO files (e.g. verify schema, verify image URLs).
- Cleanup text-based subtitle files (e.g. convert file encoding to UTF8).
- Process external subtitle files (e.g. merge or extract).
The third-party tools, libraries, and actions this project depends on.
License
Licensed under the MIT License
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论