mediafinder 0.5.4

Media file finder and player

mf - Media File Finder

A cross-platform command-line tool for finding and playing video files in large collections

Features

• 🔍 Fast file search - Uses vendored fd binary with automatic fallback to Python scanning
• 🎯 Flexible pattern matching - Glob-based search patterns with automatic wildcard wrapping
• 📁 Multi-path scanning - Search across multiple configured directories simultaneously
• 🕒 Latest additions - Find newest files by modification time
• 🎬 Media player integration - Launch files directly in VLC
• 🌐 IMDB lookup - Automatically open IMDB pages for media files
• 💾 Smart caching - Cache search results for quick access by index
• ⚙️ Flexible configuration - TOML-based config with extension filtering and path management
• 🖥️ Cross-platform - Works on Windows, Linux, and macOS

Installation

Install with uv:

uv tool install mediafinder

Quick Start

[!NOTE] If mf is shadowed by another command on your system (e.g., Metafont), use mediafinder instead — it's already installed and works exactly the same way.

1. Configure search paths where your media files are located:

mf config set search_paths "/path/to/movies" "/path/to/tv-shows"

2. Find media files matching a filename pattern:

mf find "batman" # Finds files containing "batman"
mf find "*.mp4" # Finds all MP4 files
mf find "2023" # Finds files from 2023

3. Play a file from search results:

mf play 1 # Play first result
mf play # Play random file

4. Find latest additions:

mf new # Show 20 newest files
mf new 50 # Show 50 newest files

Commands

Core Commands

• mf find [pattern] - Search for media files matching the glob pattern
• mf new [n] - Show latest additions (default: 20 files)
• mf play [index] - Play a file by index, or random file if no index given
• mf imdb <index> - Open IMDB page for a media file
• mf filepath <index> - Print full path of a search result
• mf config - Configure mf
• mf version - Print version information
• mf or mf --help - Print help

Cache Management

• mf cache / mf cache show- Show cached search results
• mf cache file - Print cache file location
• mf cache clear - Clear the cache

Cached indices remain valid until you run another find or new command that overwrites the cache.

Configuration Management

mf can be configured directly on the command line:

• mf config set <key> <values> - Set configuration values
• mf config add <key> <values> - Add values to list settings
• mf config remove <key> <values> - Remove values from list settings
• mf config get <key> - Get configuration value
• mf config list - Show the current configuration
• mf config edit - Edit config file in default editor
• mf config file - Print config file location
• mf config settings - Print a table of all available settings

Search Paths

Add multiple paths of a (scattered) collection:

mf config set search_paths "/movies" "/tv-shows" "/documentaries"

Media Extensions

Control which file types are considered media files:

mf config set media_extensions ".mp4" ".mkv" ".avi" ".mov" ".wmv"

Extension Matching

Toggle whether to filter results by media extensions:

mf config set match_extensions true # Only return configured media types
mf config set match_extensions false # Return all files matching pattern

Other Settings

• fullscreen_playback (bool): If true, mf play launches VLC with --fullscreen --no-video-title-show.
• prefer_fd (bool): Use the bundled fd scanner when possible. Automatically ignored for mtime-sorted searches (mf new) which always use the Python scanner.

Editing the Config

mf config edit resolves an editor in this order:

1. $VISUAL or $EDITOR
2. Windows: Notepad++ if present else Notepad
3. POSIX: first available of nano, vim, vi

If no editor is found, it prints the path so you can edit manually.

Input Normalization

• Boolean values accept: true, false, yes, no, y, n, on, off, 1, 0 (case-insensitive; synonyms normalized to true/false).
• Media extensions are normalized to lowercase with a leading dot (mkv → .mkv).
• Paths are stored as absolute POSIX-style strings.

Search Patterns

• Use quotes around patterns with wildcards to prevent shell expansion
• Patterns without wildcards are automatically wrapped: batman becomes *batman*
• Automatic wildcard wrapping only happens if the pattern contains none of: * ? [ ].
• Examples:
  • mf find "*.mp4" - All MP4 files
  • mf find batman - Files containing "batman"
  • mf find "*2023*1080p*" - 2023 releases in 1080p
  • mf find "s01e??" - Season 1 episodes

Integration Features

• VLC Integration: Automatically launches VLC media player
• IMDB Lookup: Uses filename parsing to find matching IMDB entries
• Smart Caching: Search results are cached for quick index-based access
• Cross-platform paths: Handles Windows and Unix path conventions
• Random Playback: mf play (without index) randomly selects a file by scanning all configured paths (not just the last cached search).

Performance

• Uses bundled fd binary for fast file scanning when possible
• Automatic fallback to Python scanning if fd unavailable
• Parallel scanning across multiple search paths

Benchmarking fd vs pure python file scanning

• All tests with hyperfine and warm caches: hyperfine --warmup 3 --runs 10 "mf find test".
• Media collection on two separate, mechanical USB drives in a file server on the local network, served via SMB for Windows and NFS for Linux clients, 16.3 TiB / 3540 files total.
• Tested on the file server itself with local file access as well as on a Linux and a Windows desktop with network file access.
• mf find can use both the fd scanner as well as the pure python one. First run was with the default setting prefer_fd = true. After that I switched to the python scanner via mf config set prefer_fd false and tested again.

Platform	Pure Python (ms)	fd Scanner (ms)	Improvement
Linux Server (local file access)	697.9 ± 17.1	443.5 ± 2.6	36% faster
Linux Desktop (NFS)	1,618.0 ± 28.0	478.2 ± 21.2	70% faster
Windows Desktop (SMB)	2,371.0 ± 90.0	1,601.0 ± 94.0	32% faster

• The fd scanner provides 32-70% performance improvement for search operations over pure python file scanning.

Requirements

• Python 3.10+
• VLC media player (for play command)
• Internet connection (for IMDB lookup)

Python & IMDb Notes

IMDb lookups rely on the cinemagoer library (imdb module), which uses an API that was deprecated in Python 3.14. Until this is fixed upstream, in 3.14 mf imdb exits gracefully without affecting other commands.

License

This project is licensed under the MIT License - see the LICENSE-MIT file for details.

Third-Party Software

This package includes the fd file finder binary, which is dual-licensed under MIT OR Apache-2.0. Copyright (c) 2017-present the fd developers.

• MIT License: See src/mf/bin/LICENSE-fd-MIT
• Apache License 2.0: See src/mf/bin/LICENSE-fd-APACHE