Manual

Warning

The following documentation is for versions prior to 1.0.1. It may contain features and usage instructions that are incompatible with the current version of mediacurator.

Name

mediacurator

Synopsis

mediacurator <command> [options]

mediacurator [list,convert] [-del]
    [-in:any,avi,divx,flv,m4v,mkv,mp4,mpg,ogm,vid,webm,wmv]
    [-filters:fferror,old,lowres,hd,720p,1080p,uhd,mpeg,mpeg4,x264,wmv3,wmv,vob]
    [-out:mkv/mp4,x265/av1]
    [-print:list,formated,verbose]
    [-dirs/-files:"/mnt/media/",,"/mnt/media2/"]

Available commands: - list: List all videos with specified filters. - convert: Convert videos to specified formats.

Options:

  • -del: Delete found results after successful operations. Use with caution.

  • -in <input>: Specify input file formats (default: any).

  • -filters <filter>: Apply filters to the selection of videos.

  • -out <output>: Specify output formats (default: mkv, x265).

  • -print <print_option>: Set print options (default: list).

  • -files <file>: Specify files to process.

  • -dirs <directory>: Specify directories to process.

For multiple files or filenames, use double comma separated values (,,).

Default options (if not specified):

  • -in: any

  • -filters: (none)

  • -out: mkv, x265

  • -print: list

Description

mediacurator is a Python command-line tool designed to manage a media database. It allows you to:

  • List all videos and their metadata, optionally filtered by specified criteria.

  • Batch find, repair, or convert videos with encoding errors.

  • Batch recode videos to modern codecs (e.g., x265, AV1) based on filters (e.g., container, codec, resolution).

Options

list

Search and list videos filtered by the user-provided parameters.

convert

Search and convert all videos filtered by the user-provided parameters.

-del:

Deletes the original videos after successful completion of operations (e.g., conversion or listing). Use with caution.

See Warnings

-in:

[any, avi, divx, flv, m4v, mkv, mp4, mpg, ogm, vid, webm, wmv]

Filters videos by file format (container extensions). The default is any, meaning all formats are included.

-filters:

[fferror, old, lowres, hd, 720p, 1080p, uhd, mpeg, mpeg4, x264, wmv3, wmv]

Filters videos based on specific criteria:

  • fferror: Select videos with encoding errors (see Errors)

  • old: Select videos using outdated codecs (anything except hevc or av1)

  • hd: Select videos in HD (720p, 1080p, UHD)

  • lowres: Select videos that are not in HD

  • uhd: Select Ultra-HD videos (width or height >= 2160)

  • 1080p: Select Full-HD videos (1440 <= width < 2160 or 1080 <= height < 2160)

  • 720p: Select HD videos (1280 <= width < 1440 or 720 <= height < 1080)

  • sd: Select standard-definition videos (480 <= height < 720)

  • subsd: Select substandard-definition videos (height < 480)

  • mpeg, mpeg4, x264, wmv3, wmv, vob: Filter by video codec

-out:

[mkv/mp4, x265/av1]

Specifies the output format for video conversions:

  • mkv: (Default) Package the output video in a Matroska container.

  • mp4: Package the output video in an MP4 container.

  • x265 or hevc: (Default) Encode the video using x265 (HEVC).

  • av1: Encode the video using AOMedia Video 1 (AV1).

-print:

[list, formated, verbose]

Specifies how the output should be displayed:

  • list: (Default) Prints video info in a concise, single-line format.

List videos (single-line output)

  • formated: Prints video info in a more readable format with line breaks.

List videos (formatted output)

  • verbose: Prints the FFmpeg output during conversions.

-dirs:

[“/mnt/media/”,,”/mnt/media2/”]

Specifies directories to scan, separated by double commas (,,).

-files:

[“/mnt/media/video.avi”,,”/mnt/media2/video2.mp4”]

Specifies individual video files to process, separated by double commas (,,).

Examples

# This command lists all videos in the specified directories that use old codecs and
# formats the output.
mediacurator list -filters:old -print:formated -dirs:"/mnt/media/",,"/mnt/media2/"

# This command converts all MPEG4 videos found in the specified directories to AV1 format
# in MP4 containers and deletes the originals.
mediacurator convert -del -filters:mpeg4 -out:av1,mp4 -dirs:"/mnt/media/",,"/mnt/media2/"

# This command converts AVI or MPG videos, displays detailed output during conversion, and
# deletes originals.
mediacurator convert -del -in:avi,mpg -print:formated,verbose -dirs:"/mnt/media/",,"/mnt/media2/"

For more examples, see Use cases

See Also

Glossary

  • Codec: A program or device that compresses and decompresses digital media.

  • Container: A file format that holds video, audio, and metadata.

  • UHD: Ultra High Definition, refers to video resolutions of 3840x2160 pixels or higher.

Error Handling

Common issues users might encounter include:

  • Encoding Errors: If videos have encoding errors, they can be filtered using the -filters fferror option.

  • Unsupported Formats: Ensure that input formats specified in -in are supported by mediacurator.

Author

Fabrice Quenneville