Maintenance Tools
Tools for optimizing media files, cleaning up the server, and tracking background jobs.
These three tools handle ongoing server maintenance — optimize media files by stripping unwanted tracks, clean up caches and orphaned data, and monitor background job progress.
optimize_media
Analyze or strip unwanted audio and subtitle tracks from MKV files to save space. Works on a single file or an entire folder (batch). Large batches (more than 3 files) run as a background job. Paths are sandboxed under the media/download roots.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
mediaPath | string | Yes | Path to a media file or folder (e.g. “anime/Invincible (2021)” or full path “/data/anime/Invincible (2021)”). |
action | enum | No | analyze (default) to show tracks, or optimize to strip unwanted tracks. |
keepAudioLangs | string[] | No | Audio language codes to keep (e.g. ["spa", "eng", "jpn"]). Others are removed. Omit to keep all. |
keepSubLangs | string[] | No | Subtitle language codes to keep (e.g. ["spa", "eng"]). Others are removed. Omit to keep all. |
removeAllSubs | boolean | No | Remove ALL subtitle tracks. Defaults to false. |
confirmToken | string | Conditional | Server-issued token required to execute action=optimize. Omit it on the first call to receive a preview and token. |
Actions
- analyze — List all audio and subtitle tracks in the target MKV file(s), including language, codec, channels, and track metadata.
- optimize — Remove audio and subtitle tracks that do not match the specified keep lists. Video tracks are always preserved. Files where nothing would change are skipped.
action=optimize is a two-step operation. The first call returns a preview and confirmToken; repeat the same arguments with that token within 5 minutes to apply changes.
Usage Example
“Analyze the tracks in anime/Invincible (2021).”
“Optimize movies/Movie (2024) keeping only English and Spanish audio and English subtitles.”
“Strip all subtitles from tv/Show/Season 01.”
cleanup_server
Clean up the server: remove Jellyfin cache info, temp files, orphan downloads, ghost entries in Sonarr/Radarr, and completed qBittorrent torrents. Runs all cleanup operations every time — there is no action selector.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
dryRun | boolean | No | Preview what would be cleaned without deleting anything. Defaults to true. |
confirmToken | string | Conditional | Server-issued token required when dryRun=false. Omit it on the first destructive call to receive a preview and token. |
Destructive Confirmation
dryRun=false is a two-step operation. The first call returns { requiresConfirmation, confirmToken, preview, message } and does not delete anything. Repeat the same arguments with confirmToken within 5 minutes to execute.
Usage Example
“Do a dry-run server cleanup.”
“Run the server cleanup for real.”
check_jobs
Check status of background operations (file moves, media optimizations, etc.). Returns progress and results for running or completed jobs.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
jobId | string | No | Specific job ID to check. Omit to see all active jobs. |
Usage Example
“Are there any background jobs running?”
“Check the status of job abc123.”