# Metadata for IINA

An IINA plugin that identifies local movies and TV episodes, shows their details, and saves metadata and artwork inside files and alongside them.

Identify movies and TV episodes in IINA. Review the match, then save metadata and artwork with your video.

Website: https://iina-metadata.thepushkarp.com
Repository: https://github.com/thepushkarp/iina-metadata

## Requirements

- Tested with IINA 1.5
- Local video files
- Free & open source

## Features

### Meet the movie you opened.

Identify movies and TV episodes from filenames and folders. View artwork, overview, cast, and crew in a Metadata sidebar.

### Check the match first.

Fix an uncertain match by title, year, or type. Review exactly what will be written before pressing Save to file.

### Let the details travel.

Write tags into supported video files, and save .nfo files and artwork alongside them for your other media apps.

## A better library starts with one file.

Open a local video in IINA, then choose Plugin → Metadata → Show Metadata. The plugin looks for a match and shows what it found.

### Recognise

Title and year help identify a movie. Episodes can use S01E02 or a season-folder layout.

```text
Spring.2019.1080p.mkv
```

### Review

Choose the right title and review the “Will write” list in the sidebar.

### Save

Save embedded tags and the selected sidecar files. Nothing is written until you choose to save.

## Compatibility

Choose embedded tags, sidecars, or both in the plugin’s preferences. Support in your player depends on its settings and the file format.

| Destination | What gets written | Required tool |
| --- | --- | --- |
| MKV / MKA / WebM | Title, tags, poster and landscape artwork | MKVToolNix |
| MP4 / M4V | iTunes-compatible metadata and cover | AtomicParsley |
| Alongside videos | .nfo, posters, backdrops and episode artwork | No tagging tools |
| Other video formats | Sidecars and artwork only | No tagging tools |

## Installation

Install the plugin, then open a local video.

### 1. Add the plugin

In IINA, go to Settings → Plugins → Install from GitHub and enter:

```text
thepushkarp/iina-metadata
```

### 2. Connect TMDB

Open Plugin → Metadata → Show Metadata and add your TMDB API Read Access Token. TV episodes can use TVmaze without a token.

### 3. Review and save

Check the match and the “Will write” list, then choose Save to file. Nothing changes until you save.

- [Download a release](https://github.com/thepushkarp/iina-metadata/releases/latest)
- [Get IINA](https://iina.io/)
- [Get a TMDB token](https://www.themoviedb.org/settings/api)

### Save tags inside MKV or MP4 files

Optional: install these tools for embedded tags. Without them, metadata and artwork can still be saved alongside your video.

```text
brew install mkvtoolnix atomicparsley
```

## Questions

### Does it change files automatically?

No. It shows a match and a list of proposed writes. You must press Save to file. Existing sidecars and artwork are moved to Trash when replaced, unless you choose to keep them.

### Does it work with Infuse or Kodi?

It supports Infuse-style and Kodi/Jellyfin-style sidecar names. In Infuse, enable Prefer Local Artwork. Infuse uses movie .nfo files, but ignores TV .nfo files. Embedded metadata also depends on Infuse’s metadata-fetching settings.

### What happens to my data?

Search terms derived from filenames/folders and IDs are sent to TMDB or TVmaze. Videos are not uploaded. The TMDB token stays in Keychain; responses are cached locally for a week.

### Can I undo a save?

Replaced sidecars and artwork are in Trash. Original MKV tags are backed up once. MP4 files do not keep a backup; check the proposed changes before saving. See the README for recovery instructions.

### Are there any format limitations?

Only local files are supported. Air-date episode filenames are not recognised; use S01E02 or a season folder. Multi-episode files get the first episode’s metadata. An MP4 rewrite can need free space about the size of the file.

## Documentation

- [Usage & configuration](https://github.com/thepushkarp/iina-metadata#using-it)
- [Infuse compatibility](https://github.com/thepushkarp/iina-metadata#seeing-it-in-infuse)
- [Agent guide](https://iina-metadata.thepushkarp.com/agents.md)

## Interactive preview

The preview shows an IINA player window with the real Metadata sidebar. Use the Metadata button or Plugin → Metadata → Show Metadata to reveal the sidebar, correct the Spring match, and try Save to file. Player controls use poster artwork and a simulated timeline; no video or audio is streamed. Metadata searches and saves use an in-memory bridge, without provider requests or file writes.

## App screenshots

Actual IINA plugin sidebar rendered with staged Spring metadata and a licensed Blender Studio poster. Nothing is written by this website.

- [Metadata](https://iina-metadata.thepushkarp.com/screenshots/movie.png): The actual IINA Metadata sidebar showing Spring, its licensed poster, a confident match, and the planned embedded metadata, NFO and poster writes.

## 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.