TinyMediaManager Ubuntu Installation and Configuration: Set Up Your Media Library Preprocessing Center Step by Step
The previous article introduced what TMM is. Now let’s get hands-on.
I’ll cover two installation methods: Direct Installation (suitable for desktop environments) and Docker Deployment (suitable for server/NAS headless operation). Choose based on your situation.
Method 1: Direct Installation on Ubuntu
TMM is written in Java, but since v4 it comes bundled with its own Java runtime — no need to install JDK/JRE separately. Just unzip and run.
1. Download
Go to the official download site release.tinymediamanager.org or the GitHub Releases page to download the Linux version:
# Download the latest version (using v5.2.12 as example)
wget https://release.tinymediamanager.org/v5.2.12/tinyMediaManager-5.2.12-linux.zip
2. Unzip
unzip tinyMediaManager-5.2.12-linux.zip -d /opt/tinymediamanager
cd /opt/tinymediamanager
3. Run
./tinyMediaManager
The first launch will display a setup wizard: choose language, theme (dark/light), update checking, etc.
4. Create Desktop Icon
If you want to launch it from the application menu:
cat > ~/.local/share/applications/tinyMediaManager.desktop <<EOF
[Desktop Entry]
Type=Application
Terminal=false
Name=tinyMediaManager
Icon=/opt/tinymediamanager/tmm.png
Exec=/opt/tinymediamanager/tinyMediaManager
Categories=AudioVideo;
EOF
5. Mount Your Media Directories
TMM won’t move your files — it only reads and writes metadata. Make sure TMM has read/write permissions to your movie/TV show directories:
# If media files are in /mnt/media/movies and /mnt/media/tvshows
chown -R $USER:$USER /mnt/media
Then add the corresponding media sources in TMM’s settings.
6. If You Need a Proxy
TMM supports configuring proxies for scraping sources individually in settings — if you need to access TMDB through a proxy, you can configure an HTTP proxy under “Settings → Connection.”
This is an essential feature for Chinese users.
Method 2: Docker Deployment (Recommended for Server/Headless Mode)
If your media server runs on a desktopless Ubuntu server or NAS, Docker is a better choice.
docker-compose.yml
version: "2.1"
services:
tinymediamanager:
image: tinymediamanager/tinymediamanager:latest
container_name: tmm
environment:
- USER_ID=1000
- GROUP_ID=1000
- ALLOW_DIRECT_VNC=true
- LC_ALL=zh_CN.UTF-8
- LANG=zh_CN.UTF-8
- PASSWORD=your_v...rd
- TZ=Asia/Shanghai
volumes:
- ./tmm_data:/data
- /path/to/movies:/media/movies
- /path/to/tvshows:/media/tv_shows
ports:
- 5900:5900 # VNC
- 4000:4000 # Web interface (TMM v5+)
restart: unless-stopped
Start it:
docker-compose up -d
Access Methods
The Docker container runs a VNC server. You can connect with a VNC client to localhost:5900 to operate the GUI.
The password is the value set in the PASSWORD environment variable above.
For TMM v5 and above, a web interface is also available: open your browser to `http://localhost:4000`.
Tip: The Docker version of TMM is designed for “must run in the background” scenarios. If you can use the desktop version, the experience is better.
Basic Configuration: Let TMM Know Your Media Library
After launching TMM, the first thing to do is add media sources.
Add Movie Directory
Menu bar → Settings → Movies → In the “Media Directory” tab, click “Add” and select your movie directory.
For example, if your movies are stored at /media/movies, add this path.
Add TV Show Directory
Same operation: Settings → TV Shows → Add media directory.
Select Scraping Sources
Settings → Movies → Scraper, choose your metadata sources:
- TheMovieDB (recommended, most comprehensive data)
- IMDb
- OFDb (good for German movies)
- MovieMeter (good for Dutch movies)
Language is recommended to be set to zh-CN so that scraped titles and descriptions are in Chinese.
Settings → Movies → Artwork, choose poster/background sources:
- TheMovieDB
- Fanart.tv
NFO Settings
Settings → Movies → NFO, make sure the following options are checked:
- ✅ Write NFO
- ✅ Use Kodi/Emby/Jellyfin compatible format
This way, after scraping, each movie directory will have a .nfo file containing complete metadata (XML format). Emby/Jellyfin reads the NFO directly during scanning — no internet connection needed.
Usage Workflow
After configuration, your daily workflow is just three steps:
1. Update Media Library
On the main screen, click “Update Media Library” → “Update All Media Directories.” TMM will scan the directories and identify movie files and existing NFO files.
The first scan of thousands of movies may take some time, as each file needs to be analyzed. Subsequent scans will be much faster — only checking for new or changed files.
2. Search and Scrape
Select all movies (Ctrl+A), click “Search and Scrape.”
TMM will query TMDB online and download metadata and posters. If auto-matching is correct, each movie takes just seconds. If matching fails, a popup lets you manually search.
3. Refresh in Your Media Server
Go back to Emby/Jellyfin and run “Scan File System” or “Refresh Metadata” on the media library. Since the NFO files already exist, scanning is nearly instantaneous.
Tips for Working with Emby/Jellyfin
The most common setup is:
- TMM does metadata preprocessing: After new movie files are placed in the media directory, scrape them in TMM to generate NFO and posters
- Emby/Jellyfin reads local data directly: Disable Emby’s auto-scraping and have it only read local NFO
Configure this in Emby:
Emby Server → Media Library → Your Movie Library → Settings → Metadata Downloaders: Uncheck all online scrapers, keeping only “Local NFO.”
This way Emby will never scrape online — all metadata is handled by TMM, with accuracy under your control.
Common Issues
Blank window after launch?
On some Linux desktop environments, Java/Swing rendering may have issues.
Fix: Force-specify the rendering pipeline at launch:
./tinyMediaManager -Dsun.java2d.opengl=true
Or set an environment variable in the terminal:
export _JAVA_OPTIONS="-Dsun.java2d.opengl=true"
./tinyMediaManager
Getting “libmediainfo not available”?
sudo apt install libmediainfo-dev
Scraping is very slow?
- Check your network connection; TMDB may need a proxy
- The first scrape of a large library is indeed slow; incremental scrapes afterward are much faster
- For the Docker version’s first scrape, use VNC to operate, then switch to command-line automation
Subtitle download not working?
Since 2024, OpenSubtitles requires a VIP account to download subtitles. Free users cannot download via API.
Summary
Installing TMM on Ubuntu is straightforward — whether you go with direct installation or Docker, you can be done in ten minutes.
Its value isn’t in the installation itself, but in establishing a workflow: new movies come in → TMM scrapes them → Emby/Jellyfin reads → watch until done. Once this is running smoothly, your media library maintenance enters “unattended mode.”
Next, I’ll cover TMM’s advanced features: batch organization tips, HTTP API automation, and how to use scripts for a fully automated pipeline.
Comments