Metadata-Version: 2.4
Name: mediafinder
Version: 0.5.4
Summary: Media file finder and player
Project-URL: Homepage, https://github.com/aplzr/mf
Project-URL: Issues, https://github.com/aplzr/mf/issues
Author-email: ap <arnepelzerprivat@gmail.com>
License: MIT License
        
        Copyright (c) 2017-present The fd developers
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE-MIT
Keywords: cli,filesystem,finder,media,player,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: cinemagoer>=2023.5.1
Requires-Dist: guessit>=3.8.0
Requires-Dist: rich>=14.2.0
Requires-Dist: tomlkit>=0.13.3
Requires-Dist: typer>=0.19.2
Provides-Extra: dev
Requires-Dist: anybadge>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=4.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.14.3; extra == 'dev'
Description-Content-Type: text/markdown

# mf - Media File Finder

<!-- Local badges generated by CI into static/: coverage (anybadge from coverage.xml line-rate), python minimum version (MIN+ from requires-python) -->
![Python Versions](./static/badge_python.svg) ![CI](https://github.com/aplzr/mf/actions/workflows/ci.yml/badge.svg?branch=main) ![Coverage](./static/badge_coverage.svg) ![Style](./static/badge_style.svg)

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

![](static/mf.svg)

## 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](https://docs.astral.sh/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:

```bash
mf config set search_paths "/path/to/movies" "/path/to/tv-shows"
```
2. **Find media files** matching a filename pattern:

```bash
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:

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

4. **Find latest additions**:
```bash
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:

```bash
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:

```bash
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`](https://github.com/sharkdp/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](LICENSE-MIT) file for details.

### Third-Party Software

This package includes the [`fd`](https://github.com/sharkdp/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`
