Skip to content
User guide

Movie Metadata User Guide

How to use Movie Metadata 0.2.5. The window is laid out in the order you work, from left to right: “① Video Files” (① 動画ファイル), “② Search for a Film” (② 映画を検索) and “③ Details to Write” (③ 書き込む内容).

App interface: Japanese. Japanese labels are shown in parentheses, for example Settings (設定).

Getting started

Movie Metadata is an app that writes information about films and programmes (metadata) into video files on your Mac (MP4, M4V, MOV). You can choose to save the written video as an MP4 separate from the original, or to overwrite the original file. Video and audio are not re-encoded, so picture and sound quality do not change.

How to install is on the download page. No special permissions are needed.

Fumi

If you’re unsure, go left to right: ①, ②, then ③.

Opening videos

  • Drag and drop videos from Finder onto the “① Video Files” (① 動画ファイル) area on the left.
  • You can also choose them with Add Files… (ファイルを追加…) below the area, or with File (ファイル) → Open Video Files… (動画ファイルを開く…) in the menu (⌘O). You can open several files at once.
  • You can also right-click a video in Finder and choose Open With (このアプリケーションで開く) → “Movie Metadata”. Your default player does not change.

Opened files are listed with the file name, the title to write and the status (Not set (未設定), Editing (編集中), Saved (保存済み) and so on). The file you click becomes the one to write to. If you open a file other than MP4, M4V or MOV, the app tells you the format is not supported.

To remove a video from the list, select it and press Remove (外す) below the area, or press the Delete key. You can also use Remove from List (リストから外す) in the right-click menu. Remove All… (すべて外す…) asks for confirmation and then removes them all. This only removes them from the list; the video files themselves are not deleted. Edits you have not yet written are lost.

When you open a video, search words and the release year are filled into “② Search for a Film” (② 映画を検索) in the middle, and a search starts automatically.

  • The search words are made from the title and release year already embedded in the video. If there are none, they are made from the file name.
  • Notes in brackets in the file name, such as “(字幕版)” or “[YTS.MX]”, and parts like “1080p”, “BluRay” and “x264” are dropped. . and _ are treated as spaces.
  • Candidates are listed newest release year first. Each shows the title, release year and source; check whether it is the work you want, then click it.
  • If it is not found, change the search words, release year, source or language, and search again with Search (検索) or Return.

Please check for yourself whether a candidate is the same work. Movie Metadata does not merge or decide on candidates automatically.

Differences between sources

SourceHow it gets dataMain information available
TMDBThe official API (credentials required)Original title, release date, poster, genre, studio, director, writer, producer, cast and roles. Japanese and English
Eiga.com (映画.com)The public search pageImages, synopsis, director, writer, producer, cast and roles (Japanese). The production year is preferred
Prime Video, HuluThe public search page and the work’s pageTitle, synopsis, images and other information on the page
Netflix, U-NEXT, Disney+, Apple TV+Finds the work on Wikipedia, then follows the article’s links (English Wikipedia, Eiga.com, Wikidata) to the work’s pageInformation on the work’s page. When there are several links, it does not choose one automatically
TVerThe data used by tver.jp’s web pagesProgramme name, episode number, air date, broadcaster, synopsis, thumbnail (landscape). Cast is not fetched
ABEMAReads abema.tv’s public search page in a browser window inside the app (it does not log in or play videos)Title, synopsis, images, genre. From episode pages, the cast, roles and staff listed there
WikipediaArticlesOriginal title, director, producer, cast and other information in the article

Sources other than TMDB have no public API, so their web pages are read. Information may not be available because of changes to how a site works, missing information on the page, missing links and so on. Being able to get an image does not mean you have permission to reuse it.

TMDB setup

The default source is TMDB. To search TMDB, you need a TMDB API Read Access Token. Until you set it, a note in red appears below the source (other sources can be used as they are).

  1. Create a TMDB account and log in.
  2. On the API settings page, apply to use the API and copy the “API Read Access Token” (free for non-commercial use).
  3. In Movie Metadata, open TMDB Settings… (TMDBの設定…) from the settings (gear) menu at the top right, paste the token and press Save and Finish (保存して完了).

The credentials are stored in your Mac’s keychain and loaded the next time the app starts. They are not put into project JSON files or videos. Saving with the field empty deletes them from the keychain. For TMDB’s terms of use and attribution, see the TMDB FAQ.

Checking and editing the details

When you click a candidate, the work’s information is filled into “③ Details to Write” (③ 書き込む内容) on the right. Clicking another candidate replaces the details.

  • The title (Japanese title), original title, release year, release date, director, writer, producer, studio, genre, short description, cover image URL, cast and roles, and synopsis can all be edited.
  • With Choose Cover Image… (カバー画像を選ぶ…), you can use an image on your Mac (PNG, JPEG and so on) as the cover.
  • With Open Source (取得元を開く), you can open the page the information came from in your browser.

If you choose a candidate while no video file is selected, the details are only displayed. To write them, select a video on the left and then choose the candidate again.

Writing to a video

  1. Press Write to Video… (動画に書き込む…) at the bottom right.
  2. Choose Save to Another Location… (別の場所へ保存…) and choose where to save. The name is prefilled with the title to write plus “.mp4” (/ and : are replaced with full-width characters). If the title is empty or the same as the original file name, it becomes “original file name.tagged.mp4”.
  3. When the export is finished, “Saved” (保存完了) appears at the bottom of the window.

Writing to several videos at once

Use this when you want to write the same details to many videos, for example a drama series.

  1. Search with the first video, choose a candidate and check the details on the right.
  2. In the list on the left, click other videos while holding the ⌘ key to add them to the selection. Clicking while holding the Shift key selects all the videos in between. Adding to the selection does not change the details shown on the right.
  3. The button at the bottom right now includes the number, for example Write to 3 Videos… (3本に書き込む…). Press it.
  4. Choose Save to Another Location… (別の場所へ保存…) and choose a destination folder. Each video is saved with its original file name (or as “original file name.tagged.mp4” if the folder is the same as the original video’s). If a file with the same name exists, the app asks whether it may be replaced.

Overwriting the original file

When you press Write to Video… (動画に書き込む…) (or Write to 3 Videos… (3本に書き込む…) for several), a screen appears where you choose how to save. If you choose Overwrite the original file (元のファイルに上書き), the original video is replaced with the written video. For MP4, the file name does not change. For M4V, the extension changes to MP4 (“録画.m4v” becomes “録画.mp4” and the original M4V is deleted; if an MP4 with the same name already exists, it is not overwritten). A replaced video cannot be restored, so if you are worried, make a copy first. Videos in MOV format are not overwritten, because the written video would be in MP4 format (use Save to Another Location… (別の場所へ保存…)).

The export is first done to a temporary file; the title, cover, duration and track layout are read back and checked, and only then is the file put in the place you specified. If something fails along the way, the original video and any file already at the destination remain as they were. With Save to Another Location… (別の場所へ保存…), you cannot save to the same place with the same name as the original video.

What is written into the MP4 is the title, description (synopsis), cast, director, genre, release date, studio (in the publisher field; for TVer programmes, the broadcaster goes in the TV network field) and cover. All fields, including writer and producer, are saved in video name.mp4.metadata.json next to the exported video. Which fields are displayed depends on the player.

Fumi

With “Save to Another Location…”, the original video stays, so you can redo it as often as you like.

TV recordings (TVer)

If the file name contains an air date or episode number such as “10月23日 放送分” (aired October 23), “第1話” (episode 1) or “#16”, the file is treated as a programme recording. The source is switched to TVer automatically, the search uses the programme name only, and the episode matching the file name is listed at the top. When you select a film file again, the source goes back to what it was.

  • You can search by typing the programme name in the search field. If you paste a https://tver.jp/episodes/ep… link or an episode ID (ep plus 8 characters), that episode is fetched directly.
  • When an air date has no year, the year is filled in as the nearest date before today.
  • TVer has no public API, so the data used by tver.jp’s web pages is read. Changes on TVer’s side may stop it from working. There is no feature for getting (downloading) videos.

ABEMA programmes

When you choose “ABEMA” as the source and search, a small browser window opens inside the app and reads abema.tv’s public search page. When the series and episode candidates are ready, the window closes automatically. Closing the window cancels the search. It does not log in or play videos.

  • If you paste a https://abema.tv/video/title/… or https://abema.tv/video/episode/… link into the search field, that title or episode is fetched directly.
  • Candidates are only those shown first in the search results.
  • It gets the title, synopsis, images and genre. On episode pages, it also gets the cast, roles and staff listed there. When the production year or staff are not listed, they are left empty rather than guessed. The date streaming started is not treated as the release date.
  • ABEMA has no public API either, so its web pages are read. Changes on ABEMA’s side may stop it from working. There is no feature for getting (downloading) videos.

Saving your work

With Save Work… (作業を保存…) in the settings (gear) menu at the top right, you can save the in-progress state of all open files to a JSON file. With Open Saved Work… (保存した作業を開く…), you can pick up where you left off. This is separate from writing to videos.

Menus and settings

About this app (このアプリについて)App menu (“Movie Metadata” at the top left of the screen). Version, copyright notice and a link to the official site
Check for Updates… (アップデートを確認…)App menu. If there is a new version, you can update right away
Check for Updates Automatically (アップデートを自動で確認)App menu. A check once a day (on by default)
Install Updates Automatically (アップデートを自動でインストール)App menu. A version that is found is prepared in the background and swapped in when you quit (on by default)
TMDB Settings… (TMDBの設定…)Settings (gear) menu at the top right. The TMDB API Read Access Token
Open Saved Work… (保存した作業を開く…) / Save Work… (作業を保存…)Settings (gear) menu at the top right. A JSON file of the in-progress state

Troubleshooting

No candidates appear
Try shortening the search words, clearing the release year, changing the source, or changing the language. If the Japanese title does not find it, you can also try the original title.
Searching TMDB does not work
Check in TMDB Settings… (TMDBの設定…) that an API Read Access Token (a long string) has been entered. Use the “API Read Access Token”, not the “API Key” (a short string).
A source suddenly stopped working
The site may have changed how it works. Try another source, and wait for a version that supports the change.
“Export failed” (書き出し失敗) appears
Check the free space and write permission at the save location. If the cover image cannot be fetched, clear the cover image field or choose an image on your Mac, then export again. With some codecs or track layouts, the video may not be exportable to MP4.
The written information does not appear in the player
Which fields are displayed depends on the player. Also check with Finder’s Get Info, or in other apps such as Music or TV.
It does not update automatically
Check that the app is in the Applications folder and opened from there. If it is opened from inside the disk image, it cannot be replaced. You can also check on the spot with Check for Updates… (アップデートを確認…) in the app menu.

If this does not solve the problem, please contact info@k386.sub.jp.

Glossary

Metadata
Information stored in a video file, such as the title, synopsis, cast and cover image.
Source
The site or service where the app looks for a work’s information. You choose it in the middle area.
API Read Access Token
Credentials for using the TMDB API. You get it on the API settings page of your TMDB account.
Export without re-encoding
Putting the video and audio data into a new file as they are. Picture and sound quality do not change, and it finishes quickly.