MediaFix

mediafix is a small Go CLI for organizing local media files using TMDB metadata.

It currently supports:

• Movies
• TV episodes
• Test mode previews
• Apply mode renames/moves
• Recursive scanning
• Custom output formats
• TMDB v4 Read Access Token from --token, TMDB_TOKEN, or local .env.local

Requirements

• Go 1.22 or newer
• A TMDB v4 Read Access Token
• Optional: Task if you want to use task install

Set your TMDB token in your shell:

set -Ux TMDB_TOKEN "your_tmdb_v4_read_access_token"

Or pass it per command:

mediafix tv /path/to/tv --token "$TMDB_TOKEN"

For local development, mediafix also loads .env.local from the current working directory when it exists:

TMDB_TOKEN=your_tmdb_v4_read_access_token

--token takes precedence over TMDB_TOKEN.

Install

With Task:

task install

This builds a release binary and installs it to:

~/.local/bin/mediafix

Make sure ~/.local/bin is in your shell path:

fish_add_path ~/.local/bin

Manual build:

go build -trimpath -ldflags="-s -w" -o ~/.local/bin/mediafix ./cmd/mediafix

Check the install:

mediafix --help
mediafix tv --help

Common Flags

--test        Preview planned changes without moving files. This is the default.
--apply       Create target directories and move files.
--recursive   Scan folders recursively.
--format      Override the target naming format.
--token       TMDB v4 Read Access Token.
--verbose     Print extra parser details.

TV Usage

Preview a TV show folder recursively:

mediafix tv --recursive /Volumes/tv/Babylon\ 5

Example input:

/Volumes/tv/Babylon 5/Babylon 5 S03/Babylon.5.S03E01.Matters.of.Honor.1080p.WEBRip.10Bit.DDP2.0.HEVC-d3g.mkv

Default TV output:

/Volumes/tv/Babylon 5/Season 03/Babylon 5 - S03E01 - Matters of Honor.mkv

In test mode, mediafix prints the planned change:

[TEST]
FROM: /Volumes/tv/Babylon 5/Babylon 5 S03/Babylon.5.S03E01.Matters.of.Honor.1080p.WEBRip.10Bit.DDP2.0.HEVC-d3g.mkv
TO:   /Volumes/tv/Babylon 5/Season 03/Babylon 5 - S03E01 - Matters of Honor.mkv

Apply the TV organization:

mediafix tv --recursive --apply /Volumes/tv/Babylon\ 5

If you run from the parent TV folder, mediafix creates the show folder:

mediafix tv --recursive /Volumes/tv

Example target:

/Volumes/tv/Babylon 5/Season 03/Babylon 5 - S03E01 - Matters of Honor.mkv

If the input path is already the show folder, mediafix avoids duplicating the show folder:

Input:  /Volumes/tv/Babylon 5
Target: /Volumes/tv/Babylon 5/Season 03/...

Supported TV filename patterns include:

Show.Name.S01E02.Episode.Title.1080p.WEBRip.mkv
Show Name - S01E02 - Episode Title.mkv
Show.Name.1x02.Episode.Title.mkv
Show.Name.S01.E02.Episode.Title.mkv

Default TV format:

{series}/Season {season:02}/{series} - S{season:02}E{episode:02} - {title}

TV format variables:

{series}
{season}
{season:02}
{episode}
{episode:02}
{title}

Custom TV format example:

mediafix tv --recursive --format "{series}/S{season:02}/{episode:02} - {title}" /Volumes/tv/Babylon\ 5

Movie Usage

Preview a movie folder:

mediafix movies /Volumes/movies

Preview recursively:

mediafix movies --recursive /Volumes/movies

Example input:

/Volumes/movies/The.Matrix.1999.REMASTERED.1080p.BluRay.x265-YAWNTiC.mkv

Default movie output:

/Volumes/movies/The Matrix (1999).mkv

Apply movie renames:

mediafix movies --apply /Volumes/movies

Default movie format:

{title} ({year})

Safety

• Test mode is the default.
• Apply mode never overwrites existing files.
• Hidden files are ignored.
• Supported video extensions are .mkv, .mp4, .avi, .mov, and .m4v.
• Target directories are created only in apply mode.
• TMDB token values are not printed.

Development

Run from source:

go run ./cmd/mediafix tv --recursive /path/to/tv
go run ./cmd/mediafix movies /path/to/movies

Run tests:

go test ./...

Build a local release binary:

go build -trimpath -ldflags="-s -w" -o mediafix ./cmd/mediafix

License

MediaFix is licensed under the GNU Affero General Public License v3.0 or later. See LICENSE.