# NFO Metadata Guide
## Document Purpose
This guide explains how to use the NFO metadata feature to enrich your anime library with TMDB metadata and artwork for Plex, Jellyfin, Emby, and Kodi.
---
## 1. Overview
### What are NFO Files?
NFO files are XML documents that contain metadata about TV shows and episodes. Media servers like Plex, Jellyfin, Emby, and Kodi use these files to display information about your library without needing to scrape external sources.
### Features
- **Automatic NFO Creation**: Generate NFO files during downloads
- **TMDB Integration**: Fetch metadata from The Movie Database
- **Image Downloads**: Poster, fanart, and logo images
- **Batch Operations**: Create/update NFO files for multiple anime
- **Web UI**: Manage NFO settings and operations
- **API Access**: Programmatic NFO management
---
## 2. Getting Started
### 2.1 Obtain TMDB API Key
1. Create a free account at https://www.themoviedb.org
2. Navigate to https://www.themoviedb.org/settings/api
3. Request an API key (select "Developer" option)
4. Copy your API key (v3 auth)
### 2.2 Configure NFO Settings
#### Via Web Interface
1. Open http://127.0.0.1:8000
2. Click **Configuration** button
3. Scroll to **NFO Settings** section
4. Enter your TMDB API key
5. Click **Test Connection** to verify
6. Configure options:
- **Auto-create during downloads**: Enable to create NFO files automatically
- **Update on library scan**: Enable to refresh existing NFO files
- **Download poster**: Episode and show poster images (poster.jpg)
- **Download logo**: Show logo images (logo.png)
- **Download fanart**: Background artwork (fanart.jpg)
- **Image size**: Select w500 (recommended), w780, or original
7. Click **Save**
#### Via Environment Variables
Add to your `.env` file:
```bash
TMDB_API_KEY=your_api_key_here
NFO_AUTO_CREATE=true
NFO_UPDATE_ON_SCAN=false
NFO_DOWNLOAD_POSTER=true
NFO_DOWNLOAD_LOGO=false
NFO_DOWNLOAD_FANART=false
NFO_IMAGE_SIZE=w500
```
#### Via config.json
Edit `data/config.json`:
```json
{
"nfo": {
"tmdb_api_key": "your_api_key_here",
"auto_create": true,
"update_on_scan": false,
"download_poster": true,
"download_logo": false,
"download_fanart": false,
"image_size": "w500"
}
}
```
---
## 3. Using NFO Features
### 3.1 Automatic NFO Creation
With `auto_create` enabled, NFO files are created automatically when downloading episodes:
1. Add episodes to download queue
2. Start queue processing
3. NFO files are created after successful downloads
4. Images are downloaded based on configuration
### 3.2 Manual NFO Creation
#### Via Web Interface
1. Navigate to the main page
2. Click **Create NFO** button next to an anime
3. Wait for completion notification
#### Via API
```bash
curl -X POST "http://127.0.0.1:8000/api/nfo/create" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"anime_id": 123,
"folder_path": "/path/to/anime/Attack on Titan"
}'
```
### 3.3 Batch NFO Creation
Create NFO files for multiple anime at once:
```bash
curl -X POST "http://127.0.0.1:8000/api/nfo/batch/create" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"anime_ids": [123, 456, 789]
}'
```
### 3.4 Update Existing NFO Files
Update NFO files with latest TMDB metadata:
```bash
curl -X POST "http://127.0.0.1:8000/api/nfo/update" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"anime_id": 123,
"folder_path": "/path/to/anime/Attack on Titan",
"force": true
}'
```
### 3.5 Check NFO Status
Check which anime have NFO files:
```bash
curl -X GET "http://127.0.0.1:8000/api/nfo/check?folder_path=/path/to/anime" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
```
Response:
```json
{
"has_tvshow_nfo": true,
"episode_nfos": [
{
"season": 1,
"episode": 1,
"has_nfo": true,
"file_path": "/path/to/anime/Season 1/S01E01.nfo"
}
],
"missing_episodes": [],
"total_episodes": 25,
"nfo_count": 25
}
```
---
## 4. File Structure
### 4.1 NFO File Locations
NFO files are created in the anime directory:
```
/path/to/anime/Attack on Titan/
├── tvshow.nfo # Show metadata
├── poster.jpg # Show poster (optional)
├── logo.png # Show logo (optional)
├── fanart.jpg # Show fanart (optional)
├── Season 1/
│ ├── S01E01.mkv
│ ├── S01E01.nfo # Episode metadata
│ ├── S01E01-thumb.jpg # Episode thumbnail (optional)
│ ├── S01E02.mkv
│ └── S01E02.nfo
└── Season 2/
├── S02E01.mkv
└── S02E01.nfo
```
### 4.2 tvshow.nfo Format
```xml
Attack on Titan
進撃の巨人
Attack on Titan
Attack on Titan
8.5
2013
Humans are nearly exterminated by giant creatures...
24
TV-MA
2013-04-07
Ended
Wit Studio
Animation
Action
Sci-Fi & Fantasy
1429
https://image.tmdb.org/t/p/w500/...
https://image.tmdb.org/t/p/original/...
```
### 4.3 Episode NFO Format
```xml
To You, in 2000 Years: The Fall of Shiganshina, Part 1
Attack on Titan
1
1
1
1
After a hundred years of peace...
24
2013-04-07
8.2
63056
https://image.tmdb.org/t/p/w500/...
```
---
## 5. API Reference
### 5.1 Check NFO Status
**Endpoint**: `GET /api/nfo/check`
**Query Parameters**:
- `folder_path` (required): Absolute path to anime directory
**Response**:
```json
{
"has_tvshow_nfo": true,
"episode_nfos": [
{
"season": 1,
"episode": 1,
"has_nfo": true,
"file_path": "/path/to/S01E01.nfo"
}
],
"missing_episodes": [],
"total_episodes": 25,
"nfo_count": 25
}
```
### 5.2 Create NFO Files
**Endpoint**: `POST /api/nfo/create`
**Request Body**:
```json
{
"anime_id": 123,
"folder_path": "/path/to/anime/Attack on Titan"
}
```
**Response**:
```json
{
"success": true,
"message": "NFO files created successfully",
"files_created": ["tvshow.nfo", "S01E01.nfo", "S01E02.nfo"],
"images_downloaded": ["poster.jpg", "S01E01-thumb.jpg"]
}
```
### 5.3 Update NFO Files
**Endpoint**: `POST /api/nfo/update`
**Request Body**:
```json
{
"anime_id": 123,
"folder_path": "/path/to/anime",
"force": false
}
```
**Response**:
```json
{
"success": true,
"message": "NFO files updated successfully",
"files_updated": ["tvshow.nfo", "S01E01.nfo"]
}
```
### 5.4 View NFO Content
**Endpoint**: `GET /api/nfo/view`
**Query Parameters**:
- `file_path` (required): Absolute path to NFO file
**Response**:
```json
{
"content": "",
"file_path": "/path/to/tvshow.nfo",
"exists": true
}
```
### 5.5 Get Media Status
**Endpoint**: `GET /api/nfo/media/status`
**Query Parameters**:
- `folder_path` (required): Absolute path to anime directory
**Response**:
```json
{
"poster_exists": true,
"poster_path": "/path/to/poster.jpg",
"logo_exists": false,
"logo_path": null,
"fanart_exists": true,
"fanart_path": "/path/to/fanart.jpg",
"episode_thumbs": [
{
"season": 1,
"episode": 1,
"exists": true,
"path": "/path/to/S01E01-thumb.jpg"
}
]
}
```
### 5.6 Download Media
**Endpoint**: `POST /api/nfo/media/download`
**Request Body**:
```json
{
"folder_path": "/path/to/anime",
"anime_id": 123,
"download_poster": true,
"download_logo": false,
"download_fanart": false,
"image_size": "w500"
}
```
**Response**:
```json
{
"success": true,
"message": "Media downloaded successfully",
"downloaded": ["poster.jpg", "S01E01-thumb.jpg"]
}
```
### 5.7 Batch Create NFO
**Endpoint**: `POST /api/nfo/batch/create`
**Request Body**:
```json
{
"anime_ids": [123, 456, 789]
}
```
**Response**:
```json
{
"success": true,
"results": [
{
"anime_id": 123,
"success": true,
"message": "Created successfully"
},
{
"anime_id": 456,
"success": false,
"error": "Folder not found"
}
]
}
```
### 5.8 Find Missing NFOs
**Endpoint**: `GET /api/nfo/missing`
**Response**:
```json
{
"anime_list": [
{
"anime_id": 123,
"title": "Attack on Titan",
"folder_path": "/path/to/anime/Attack on Titan",
"missing_tvshow_nfo": false,
"missing_episode_count": 3,
"total_episodes": 25
}
]
}
```
---
## 6. Troubleshooting
### 6.1 NFO Files Not Created
**Problem**: NFO files are not being created during downloads.
**Solutions**:
1. Verify TMDB API key is configured correctly
2. Check `auto_create` is enabled in settings
3. Ensure anime directory has write permissions
4. Check logs for error messages
5. Test TMDB connection using "Test Connection" button
### 6.2 Invalid TMDB API Key
**Problem**: TMDB validation fails with "Invalid API key".
**Solutions**:
1. Verify API key is copied correctly (no extra spaces)
2. Ensure you're using the v3 API key (not v4)
3. Check API key is active on TMDB website
4. Try regenerating API key on TMDB
### 6.3 Images Not Downloading
**Problem**: NFO files are created but images are missing.
**Solutions**:
1. Enable image downloads in settings (poster/logo/fanart)
2. Verify TMDB API key is valid
3. Check network connectivity to TMDB servers
4. Ensure sufficient disk space
5. Check file permissions in anime directory
### 6.4 Incorrect Metadata
**Problem**: NFO contains wrong show information.
**Solutions**:
1. Verify anime title matches TMDB exactly
2. Use TMDB ID if available for accurate matching
3. Update NFO files with `force=true` to refresh metadata
4. Check TMDB website for correct show information
### 6.5 Permission Errors
**Problem**: "Permission denied" when creating NFO files.
**Solutions**:
1. Check anime directory permissions: `chmod 755 /path/to/anime`
2. Ensure application user has write access
3. Verify directory ownership: `chown -R user:group /path/to/anime`
4. Check parent directories are accessible
### 6.6 Slow NFO Creation
**Problem**: NFO creation takes a long time.
**Solutions**:
1. Reduce image size (use w500 instead of original)
2. Disable unnecessary images (logo, fanart)
3. Create NFOs in batches during off-peak hours
4. Check network speed to TMDB servers
5. Verify disk I/O performance
---
## 7. Best Practices
### 7.1 Configuration Recommendations
- **Image Size**: Use `w500` for optimal balance of quality and storage
- **Auto-create**: Enable for new downloads
- **Update on scan**: Disable to avoid unnecessary TMDB API calls
- **Poster**: Always enable for show and episode thumbnails
- **Logo/Fanart**: Enable only if your media server supports them
### 7.2 Maintenance
- **Regular Updates**: Update NFO files quarterly to get latest metadata
- **Backup**: Include NFO files in your backup strategy
- **Validation**: Periodically check missing NFOs using `/api/nfo/missing`
- **API Rate Limits**: Be mindful of TMDB API rate limits when batch processing
### 7.3 Performance
- **Batch Operations**: Use batch endpoints for multiple anime
- **Off-Peak Processing**: Create NFOs during low-activity periods
- **Image Optimization**: Use smaller image sizes for large libraries
- **Selective Updates**: Only update NFOs when metadata changes
### 7.4 Media Server Integration
#### Plex
- Use "Personal Media Shows" agent
- Enable "Local Media Assets" scanner
- Place NFO files in anime directories
- Refresh metadata after creating NFOs
#### Jellyfin
- Use "NFO" metadata provider
- Enable in Library settings
- Order providers: NFO first, then online sources
- Scan library after NFO creation
#### Emby
- Enable "NFO" metadata reader
- Configure in Library advanced settings
- Use "Prefer embedded metadata" option
- Refresh metadata after updates
#### Kodi
- NFO files are automatically detected
- No additional configuration needed
- Update library to see changes
---
## 8. Advanced Usage
### 8.1 Custom NFO Templates
You can customize NFO generation by modifying the NFO service:
```python
# src/core/services/nfo_creator.py
def generate_tvshow_nfo(self, metadata: dict) -> str:
# Add custom fields or modify structure
pass
```
### 8.2 Bulk Operations
Create NFOs for entire library:
```bash
# Get all anime without NFOs
curl -X GET "http://127.0.0.1:8000/api/nfo/missing" \
-H "Authorization: Bearer $TOKEN" \
| jq -r '.anime_list[].anime_id' \
| xargs -I{} curl -X POST "http://127.0.0.1:8000/api/nfo/batch/create" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"anime_ids": [{}]}'
```
### 8.3 Scheduled Updates
Use the scheduler API to refresh NFOs automatically:
```bash
# Schedule weekly NFO updates (rescan runs Sunday at 03:00)
curl -X POST "http://127.0.0.1:8000/api/scheduler/config" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"schedule_time": "03:00",
"schedule_days": ["sun"],
"auto_download_after_rescan": false
}'
```
---
## 9. Related Documentation
- [API.md](API.md) - Complete API reference
- [CONFIGURATION.md](CONFIGURATION.md) - All configuration options
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
- [DEVELOPMENT.md](DEVELOPMENT.md) - Development guide
---
## 10. Tag Reference
The table below lists every XML tag written to `tvshow.nfo` and its source in
the TMDB API response. All tags are written whenever the NFO is created or
updated via `create_tvshow_nfo()` / `update_tvshow_nfo()`.
| NFO tag | TMDB source field | Required |
| --------------- | ----------------------------------------------------- | -------- |
| `title` | `name` | ✅ |
| `originaltitle` | `original_name` | ✅ |
| `showtitle` | `name` (same as `title`) | ✅ |
| `sorttitle` | `name` (same as `title`) | ✅ |
| `year` | First 4 chars of `first_air_date` | ✅ |
| `plot` | `overview` | ✅ |
| `outline` | `overview` (same as `plot`) | ✅ |
| `tagline` | `tagline` | optional |
| `runtime` | `episode_run_time[0]` | ✅ |
| `premiered` | `first_air_date` | ✅ |
| `status` | `status` | ✅ |
| `mpaa` | US content rating from `content_ratings.results` | optional |
| `fsk` | DE content rating (written as `mpaa` when preferred) | optional |
| `imdbid` | `external_ids.imdb_id` | ✅ |
| `tmdbid` | `id` | ✅ |
| `tvdbid` | `external_ids.tvdb_id` | optional |
| `genre` | `genres[].name` (one element per genre) | ✅ |
| `studio` | `networks[].name` (one element per network) | ✅ |
| `country` | `origin_country[]` or `production_countries[].name` | ✅ |
| `actor` | `credits.cast[]` (top 10, with name/role/thumb) | ✅ |
| `watched` | Always `false` on creation | ✅ |
| `dateadded` | System clock at creation time (`YYYY-MM-DD HH:MM:SS`) | ✅ |
The mapping logic lives in `src/core/utils/nfo_mapper.py` (`tmdb_to_nfo_model`).
The XML serialisation lives in `src/core/utils/nfo_generator.py`
(`generate_tvshow_nfo`).
---
## 11. Automatic NFO Repair
Every time the server starts, Aniworld scans all existing `tvshow.nfo` files and
automatically repairs any that are missing required tags.
### How It Works
1. **Scan** — `perform_nfo_repair_scan()` in
`src/server/services/initialization_service.py` is called from the FastAPI
lifespan after `perform_media_scan_if_needed()`.
2. **Detect** — `nfo_needs_repair(nfo_path)` from
`src/core/services/nfo_repair_service.py` parses each `tvshow.nfo` with
`lxml` and checks for the 13 required tags listed below.
3. **Repair** — Series whose NFO is incomplete are queued for background reload
via `BackgroundLoaderService.add_series_loading_task()`. The background
loader re-fetches metadata from TMDB and rewrites the NFO with all tags
populated.
### Tags Checked (13 required)
| XPath | Tag name |
| ----------------- | --------------- |
| `./title` | `title` |
| `./originaltitle` | `originaltitle` |
| `./year` | `year` |
| `./plot` | `plot` |
| `./runtime` | `runtime` |
| `./premiered` | `premiered` |
| `./status` | `status` |
| `./imdbid` | `imdbid` |
| `./genre` | `genre` |
| `./studio` | `studio` |
| `./country` | `country` |
| `./actor/name` | `actor/name` |
| `./watched` | `watched` |
### Log Messages
| Message | Meaning |
| ----------------------------------------------------------- | ------------------------------------------------- |
| `NFO repair scan complete: 0 of N series queued for repair` | All NFOs are complete — no action needed |
| `NFO repair scan complete: X of N series queued for repair` | X series had incomplete NFOs and have been queued |
| `NFO repair scan skipped: TMDB API key not configured` | Set `tmdb_api_key` in `data/config.json` |
| `NFO repair scan skipped: anime directory not configured` | Set `anime_directory` in `data/config.json` |
### Triggering a Manual Repair
You can also repair a single series on demand via the API:
```http
POST /api/nfo/update/{series_key}
```
This calls `NFOService.update_tvshow_nfo()` directly and overwrites the existing
`tvshow.nfo` with fresh data from TMDB.
### Source Files
| File | Purpose |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `src/core/services/nfo_repair_service.py` | `REQUIRED_TAGS`, `parse_nfo_tags`, `find_missing_tags`, `nfo_needs_repair`, `NfoRepairService` |
| `src/server/services/initialization_service.py` | `perform_nfo_repair_scan` startup hook |
| `src/server/fastapi_app.py` | Wires `perform_nfo_repair_scan` into the lifespan |
---
## 12. Support
### Getting Help
- Check logs in `logs/` directory for error details
- Review [TESTING.md](TESTING.md) for test coverage
- Consult [DATABASE.md](DATABASE.md) for NFO status schema
### Common Issues
See section 6 (Troubleshooting) for solutions to common problems.
### TMDB Resources
- TMDB API Documentation: https://developers.themoviedb.org/3
- TMDB Support: https://www.themoviedb.org/talk
- TMDB API Status: https://status.themoviedb.org/