# MLS — Media LS

A terminal-native media and document browser with previews, metadata, filters, and structured JSON or NDJSON output.

Browse videos, audio, images, and documents in your terminal. Inspect their metadata or export it as JSON. Everything runs locally.

Website: https://mls.thepushkarp.com
Repository: https://github.com/thepushkarp/mls

## Requirements

- Audio, video, images & documents
- TUI + JSON
- MIT licensed

## Features

### Look inside, without opening.

See duration, resolution, codecs, camera details, and document metadata while moving through your files.

### Find the files that fit.

Filter by metadata, sort the results, and limit the output. Fuzzy search is there when you remember part of a name.

### A browser. Also a building block.

Get a TUI in the terminal and streaming NDJSON when piped. Request a single JSON document with --json.

## One command. Two ways to work.

Browse interactively, then take the same metadata into scripts and coding-agent workflows.

### Browse your collection

Navigate files with previews and metadata.

```text
mls ~/Videos ~/Music
```

### Find longer videos

Filter, sort, and cap the results in one command.

```text
mls --json --filter 'duration_ms > 60000' \
  --sort duration_ms:desc --limit 10 ~/Videos
```

### Inspect one file

Get detailed JSON metadata for a file.

```text
mls info clip.mp4
```

## Compatibility

Document metadata is extracted natively in Rust. Media probing, thumbnails, and playback use dedicated local tools.

| Files | What you can inspect | Requirements |
| --- | --- | --- |
| Video & audio | Duration, codecs, bitrate, resolution | ffprobe / ffmpeg |
| Images | Dimensions, camera and EXIF metadata | ffprobe / ffmpeg |
| Documents | Pages, author, sheets and format details | No external probe tools |
| Playback | Play video and audio locally | mpv |

## Installation

Homebrew is the simplest option on macOS. The formula includes ffmpeg and mpv.

### 1. Install with Homebrew

Installs the mls binary and media tools. Add trash separately if you want safe deletion in triage mode.

```text
brew install thepushkarp/tap/mls
```

### 2. Open a folder

The interactive TUI appears when output is a terminal. Use arrow keys or hjkl to navigate; press ? for help.

```text
mls ~/Videos
```

### 3. Or install with Cargo

The crate is named media-ls; the command is mls. Install ffmpeg and mpv separately for media probing and playback.

```text
cargo install media-ls
```

- [Get Homebrew](https://brew.sh/)
- [Crates.io package](https://crates.io/crates/media-ls)

## Questions

### Does MLS upload my files?

No. Browsing and metadata extraction run locally. You choose what to do with the structured output.

### What is the difference between JSON and NDJSON?

--json returns one document containing entries, summary, and errors. --ndjson streams records as files are probed. Piping output selects NDJSON automatically; use --json explicitly when your consumer expects one document.

### Which document types work?

PDF, DOCX, XLSX, PPTX, ODF, legacy Office formats, CSV, TSV, TXT, and Markdown are supported. Available fields vary by format.

### Can I play or clean up files?

Use mls play for playback through mpv. mls triage provides an interactive keep/delete workflow. Install trash to move deleted files to Trash; triage can change your files.

### What does an agent need?

Use explicit --json or --ndjson output, inspect errors and exit codes, and keep playback or triage separate from read-only inspection. The agent guide includes examples and the JSON reference.

## Documentation

- [CLI & JSON reference](https://github.com/thepushkarp/mls#usage)
- [Supported formats](https://github.com/thepushkarp/mls#supported-formats)
- [Agent guide](https://mls.thepushkarp.com/agents.md)

## Interactive preview

The preview recreates the MLS terminal in a Mac terminal window. Navigate folders with arrows or h/j/k/l and Enter; use / to filter, s/S to sort, 1–5 for kind filters, Space to mark, i for metadata, and p/P and [/] for mock playback. q exits to a sample prompt; running mls opens the browser again. Music includes WAV and FLAC metadata from real MLS output. File selection updates the JSON example. No local files are inspected or modified.

## App screenshots

Real MLS terminal output from generated sample files, with folder navigation, video thumbnails, metadata, and keyboard shortcuts.

- [File browser](https://mls.thepushkarp.com/screenshots/browse.png): Actual MLS terminal browsing generated sample clips from Blender Studio posters, with folders, files, thumbnail, codec metadata, and keyboard shortcuts.

## Artwork credits

- [Spring — Pillar poster](https://studio.blender.org/projects/spring/) by Blender Studio, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). [Licensed source](https://studio.blender.org/projects/api/assets/909/?site_context=featured_artwork). Reproduced unchanged and scaled to fit.
- [Charge — official movie poster](https://studio.blender.org/projects/charge/) by Blender Studio, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). [Licensed source](https://studio.blender.org/projects/api/assets/6234/?site_context=featured_artwork). Reproduced unchanged and scaled to fit.
- [Sprite Fright — simple poster](https://studio.blender.org/projects/sprite-fright/) by Blender Studio, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). [Licensed source](https://studio.blender.org/projects/api/assets/5448/?site_context=featured_artwork). Reproduced unchanged and scaled to fit.