lukas.pupkalipinski/Aniworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add NFO metadata integration tasks with media files

Browse Source 
- Add 9 comprehensive tasks for tvshow.nfo creation
- Include poster.jpg, logo.png, fanart.jpg management
- Integrate TMDB API scraping from external scraper repo
- Add extensive testing requirements (>85% coverage)
- Include download flow integration and UI features
- Add database tracking without manual migration
- Total estimated time: 25-30 hours
This commit is contained in:
Lukas
2026-01-11 20:07:17 +01:00
parent 40ffb99c97
commit 9a1c9b39ee
1 changed files with 803 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

803
docs/instructions.md
View File

@@ -86,6 +86,8 @@ conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.
7. **Monitoring**: Implement comprehensive monitoring and alerting
8. **Maintenance**: Plan for regular maintenance and updates
---
## Task Completion Checklist
For each task completed:
@@ -107,3 +109,804 @@ For each task completed:
---
## TODO List:
### 🎬 NFO Metadata Integration
#### Task 1: Add NFO File Support to Core Entities
**Priority:** High
**Estimated Time:** 2-3 hours
Create support for tvshow.nfo metadata files in the core domain layer.
**Implementation Steps:**
1. **Add NFO Path Property to Serie Class** ([src/core/entities/series.py](../src/core/entities/series.py))
- Add `nfo_path` optional property to track tvshow.nfo file location
- Add `has_nfo` method to check if tvshow.nfo exists
- Add properties to check for media files: `has_poster()`, `has_logo()`, `has_fanart()`
- Update `to_dict()` and `from_dict()` to include nfo metadata
2. **Update SerieList Class** ([src/core/entities/SerieList.py](../src/core/entities/SerieList.py))
- Modify `load_series()` to check for tvshow.nfo files
- Check for associated media files (poster.jpg, logo.png, fanart.jpg)
- Add logging for series without tvshow.nfo or media files
- Track NFO and media file status during series loading
**Acceptance Criteria:**
- [ ] Serie class has nfo_path property
- [ ] Serie class can check if tvshow.nfo exists
- [ ] SerieList logs missing NFO files
- [ ] Existing functionality remains unchanged
- [ ] Unit tests pass
- [ ] Test coverage > 90% for new code
**Testing Requirements:**
- Test `nfo_path` property getter/setter
- Test `has_nfo()` method with existing and missing files
- Test `has_poster()`, `has_logo()`, `has_fanart()` methods
- Test `to_dict()` includes NFO metadata
- Test `from_dict()` correctly loads NFO metadata
- Test SerieList NFO detection during load
- Test SerieList media file detection during load
- Test logging output for missing NFO and media files
- Mock filesystem operations in tests
**Files to Modify:**
- [src/core/entities/series.py](../src/core/entities/series.py)
- [src/core/entities/SerieList.py](../src/core/entities/SerieList.py)
- Add tests to `tests/unit/test_serie_class.py`
- Add tests to `tests/unit/test_serie_list.py`
---
#### Task 2: Create NFO Models and Schemas
**Priority:** High
**Estimated Time:** 3-4 hours
Create Pydantic models for NFO metadata based on Kodi/XBMC standard.
**Implementation Steps:**
1. **Create NFO Models Module** (`src/core/entities/nfo_models.py`)
```python
# Create Pydantic models for:
- TVShowNFO: Main tvshow.nfo structure
- ActorInfo: Actor/cast information
- RatingInfo: Rating information (TMDB, IMDB, etc.)
- ImageInfo: Thumbnail, fanart, logos
```
2. **Model Fields (based on scraper/tvshow.nfo example):**
- Basic: title, originaltitle, showtitle, year, plot, runtime
- IDs: tmdbid, imdbid, tvdbid
- Status: premiered, status, genre, studio
- Media: thumb (poster URLs), fanart (fanart URLs), clearlogo (logo URLs)
- Local Media: local poster.jpg, logo.png, fanart.jpg paths
- Cast: actor list with name, role, thumb
- Additional: mpaa, country, tag
**Note:** NFO files should reference both remote TMDB URLs and local file paths for media:
```xml
<thumb aspect="poster">https://image.tmdb.org/t/p/original/...</thumb>
<thumb aspect="logo">https://image.tmdb.org/t/p/original/...</thumb>
<fanart>
<thumb>https://image.tmdb.org/t/p/original/...</thumb>
</fanart>
```
3. **Add Validation:**
- Date format validation (YYYY-MM-DD)
- URL validation for image paths
- Required vs optional fields
- Default values where appropriate
**Acceptance Criteria:**
- [ ] NFO models created with comprehensive field coverage
- [ ] Models match Kodi/XBMC standard format
- [ ] Pydantic validation works correctly
- [ ] Can serialize to/from dict
- [ ] Type hints throughout
- [ ] Test coverage > 95% for models
**Testing Requirements:**
- Test all model fields with valid data
- Test required vs optional field validation
- Test date format validation (YYYY-MM-DD)
- Test URL validation for image paths
- Test invalid data rejection
- Test default values
- Test serialization to dict
- Test deserialization from dict
- Test nested model validation (ActorInfo, RatingInfo, etc.)
- Test edge cases (empty strings, None values, special characters)
- Use parametrized tests for multiple scenarios
**Files to Create:**
- `src/core/entities/nfo_models.py`
- `tests/unit/test_nfo_models.py`
---
#### Task 3: Adapt Scraper Code for NFO Generation
**Priority:** High
**Estimated Time:** 4-5 hours
Adapt code from `/home/lukas/Volume/repo/scraper/` to create tvshow.nfo files using TMDB API.
**Implementation Steps:**
1. **Copy and Adapt Scraper Code**
- Review code structure in `/home/lukas/Volume/repo/scraper/src/scraper/`
- Copy relevant modules: `api/tmdb_client.py`, `services/metadata_service.py`, `utils/xml_utils.py`
- Adapt to fit AniworldMain project structure and coding standards
- Update `requirements.txt` with TMDB API dependencies (requests, lxml)
- Add configuration for TMDB API key
2. **Create NFO Service** (`src/core/services/nfo_service.py`)
```python
class NFOService:
"""Service for creating and managing tvshow.nfo files."""
def __init__(self, tmdb_client, metadata_service):
# Initialize with scraper components
async def check_nfo_exists(self, serie_folder: str) -> bool:
"""Check if tvshow.nfo exists for a series."""
async def create_tvshow_nfo(
self,
serie_name: str,
serie_folder: str,
year: Optional[int] = None
) -> Path:
"""Create tvshow.nfo by scraping TMDB."""
async def update_tvshow_nfo(self, serie_folder: str) -> Path:
"""Update existing tvshow.nfo with fresh data."""
```
3. **Implement TMDB Search and Scraping:**
- Adapt TMDB client code from `/home/lukas/Volume/repo/scraper/src/scraper/api/tmdb_client.py`
- Search TMDB for series by name
- Handle multiple search results (prompt user or use best match)
- Download series metadata
- Adapt XML generation code from `/home/lukas/Volume/repo/scraper/src/scraper/utils/xml_utils.py`
- Generate tvshow.nfo with proper Kodi/XBMC format
- Save to series folder
4. **Implement Media File Downloads:**
- Download poster.jpg from TMDB poster URL (w500 or original size)
- Download logo.png from TMDB logo URL (if available)
- Download fanart.jpg from TMDB backdrop URL (original size)
- Save files to series folder with standard names:
- `{serie_folder}/poster.jpg`
- `{serie_folder}/logo.png`
- `{serie_folder}/fanart.jpg`
- Handle missing images gracefully (not all series have logos)
- Add retry logic for failed downloads
- Validate downloaded images (check file size, format)
- Update NFO to reference local files
5. **Add Configuration** ([src/config/settings.py](../src/config/settings.py))
- Add TMDB_API_KEY setting
- Add NFO_AUTO_CREATE boolean setting
- Add NFO_UPDATE_ON_SCAN boolean setting
- Add NFO_DOWNLOAD_POSTER boolean setting (default: true)
- Add NFO_DOWNLOAD_LOGO boolean setting (default: true)
- Add NFO_DOWNLOAD_FANART boolean setting (default: true)
- Add NFO_IMAGE_SIZE setting (w500/original, default: original)
**Acceptance Criteria:**
- [ ] Code adapted from scraper repo and integrated
- [ ] NFOService can check for existing tvshow.nfo
- [ ] Can create new tvshow.nfo from TMDB data
- [ ] Downloads poster.jpg, logo.png, fanart.jpg from TMDB
- [ ] Handles missing images gracefully (logo may not exist)
- [ ] Saves media files with correct names and locations
- [ ] NFO references both remote URLs and local files
- [ ] Handles search ambiguity gracefully
- [ ] Saves NFO files to correct locations
- [ ] Proper error handling and logging
- [ ] Configuration settings work
- [ ] Follows AniworldMain coding standards
- [ ] Unit tests pass with > 85% coverage
**Testing Requirements:**
- **TMDBClient Tests:**
- Mock all API calls with responses
- Test successful series search
- Test handling of multiple search results
- Test series details retrieval
- Test rate limiting
- Test API error handling (404, 401, 500)
- Test network timeout handling
- Test invalid API key
- **NFOService Tests:**
- Mock filesystem operations
- Mock TMDB client responses
- Test `check_nfo_exists()` with existing/missing files
- Test `create_tvshow_nfo()` success path
- Test error handling (no search results, API failures)
- Test handling of ambiguous search results
- Test file writing and permissions
- Test update existing NFO
- **NFO Generator Tests:**
- Test XML generation with complete data
- Test XML generation with minimal data
- Test XML escaping for special characters
- Test generated XML validates against Kodi schema
- Compare output with reference NFO from scraper repo
- **Media Download Tests:**
- Mock HTTP requests for image downloads
- Test successful poster download
- Test successful logo download (when available)
- Test successful fanart download
- Test handling of missing logo (common case)
- Test handling of 404 errors
- Test image validation (file size, format)
- Test retry logic on failures
- Test file naming and location
- Test skipping existing files
**Files to Create:**
- `src/core/services/nfo_service.py`
- `src/core/services/tmdb_client.py` (adapted from scraper)
- `src/core/utils/nfo_generator.py` (adapted from scraper's xml_utils.py)
- `src/core/utils/image_downloader.py` (for downloading media files)
- `tests/unit/test_nfo_service.py`
- `tests/unit/test_tmdb_client.py`
- `tests/unit/test_nfo_generator.py`
- `tests/unit/test_image_downloader.py`
- `tests/fixtures/tmdb_responses.json` (mock API responses)
- `tests/fixtures/sample_poster.jpg` (test image)
- `tests/fixtures/sample_logo.png` (test image)
- `tests/fixtures/sample_fanart.jpg` (test image)
**Files to Modify:**
- [src/config/settings.py](../src/config/settings.py)
- `requirements.txt`
**Reference Files from Scraper Repo:**
- `/home/lukas/Volume/repo/scraper/src/scraper/api/tmdb_client.py`
- `/home/lukas/Volume/repo/scraper/src/scraper/services/metadata_service.py`
- `/home/lukas/Volume/repo/scraper/src/scraper/services/asset_service.py` (for image downloads)
- `/home/lukas/Volume/repo/scraper/src/scraper/utils/xml_utils.py`
- `/home/lukas/Volume/repo/scraper/tvshow.nfo` (example output format)
---
#### Task 4: Add NFO Check to Download Flow
**Priority:** High
**Estimated Time:** 2-3 hours
Integrate NFO checking into the download workflow - check for tvshow.nfo before downloading, create if missing.
**Implementation Steps:**
1. **Modify SeriesApp Download Logic** ([src/core/SeriesApp.py](../src/core/SeriesApp.py))
```python
async def download(
self,
serie_folder: str,
season: int,
episode: int,
key: str,
language: str = "German Dub",
item_id: Optional[str] = None,
) -> bool:
# 1. Check if tvshow.nfo exists
# 2. Check if media files exist (poster.jpg, logo.png, fanart.jpg)
# 3. If not and NFO_AUTO_CREATE=true, create NFO and download media
# 4. Continue with download as normal
```
2. **Add Progress Callbacks:**
- Report NFO check progress
- Report NFO creation progress
- Update UI with NFO status
3. **Add NFO Check to Rescan:**
- During rescan, identify series without tvshow.nfo
- Optionally batch-create missing NFO files
- Report statistics
**Acceptance Criteria:**
- [ ] Download checks for tvshow.nfo before proceeding
- [ ] Checks for media files (poster.jpg, logo.png, fanart.jpg)
- [ ] Creates NFO and downloads media if missing and auto-create enabled
- [ ] Progress updates shown to user (NFO + each media file)
- [ ] Doesn't break existing download flow
- [ ] Rescan identifies missing NFOs and media files
- [ ] Proper error handling if NFO/media creation fails
- [ ] Missing media doesn't block episode download
- [ ] All integration tests pass
- [ ] No regression in existing tests
**Testing Requirements:**
- **Integration Tests:**
- Test download with existing NFO and media (should skip creation)
- Test download without NFO (auto-create enabled, downloads media)
- Test download without NFO (auto-create disabled)
- Test download with NFO but missing media files
- Test NFO creation failure doesn't block download
- Test media download failure doesn't block download
- Test progress callbacks are fired for NFO + each media file
- Test rescan identifies series without NFOs and media
- Test batch NFO and media creation during rescan
- **Unit Tests:**
- Mock NFOService in SeriesApp tests
- Test NFO check logic isolated
- Test configuration flag handling
- **Regression Tests:**
- Run all existing download tests
- Verify no performance degradation
- Test backward compatibility
**Files to Modify:**
- [src/core/SeriesApp.py](../src/core/SeriesApp.py)
- [src/core/SerieScanner.py](../src/core/SerieScanner.py)
- `tests/integration/test_download_flow.py`
- `tests/unit/test_series_app.py`
---
#### Task 5: Add NFO Management API Endpoints
**Priority:** Medium
**Estimated Time:** 3-4 hours
Create REST API endpoints for NFO management.
**Implementation Steps:**
1. **Create NFO API Router** (`src/server/api/nfo.py`)
```python
# Endpoints:
GET /api/nfo/{serie_id}/check # Check if NFO and media exist
POST /api/nfo/{serie_id}/create # Create new NFO and download media
PUT /api/nfo/{serie_id}/update # Update existing NFO and refresh media
GET /api/nfo/{serie_id}/content # Get NFO content
GET /api/nfo/{serie_id}/media/status # Get media files status
POST /api/nfo/{serie_id}/media/download # Download missing media files
POST /api/nfo/batch/create # Batch create missing NFOs and media
GET /api/nfo/missing # List series without NFOs or media
```
2. **Create Request/Response Models** (`src/server/models/nfo.py`)
- NFOCheckResponse (includes media file status)
- NFOCreateRequest (includes media download options)
- NFOBatchCreateRequest
- NFOMissingResponse
- MediaStatusResponse (has_poster, has_logo, has_fanart)
- MediaDownloadRequest (specify which files to download)
3. **Add to FastAPI App** ([src/server/fastapi_app.py](../src/server/fastapi_app.py))
- Register NFO router
- Add NFO service to dependencies
**Acceptance Criteria:**
- [ ] All endpoints implemented and working
- [ ] Proper authentication/authorization
- [ ] Request validation with Pydantic
- [ ] Comprehensive error handling
- [ ] API documentation updated
- [ ] Integration tests pass
- [ ] Test coverage > 90% for endpoints
**Testing Requirements:**
- **Endpoint Tests (for each endpoint):**
- Test successful response (200/201)
- Test authentication required (401)
- Test authorization (403 if applicable)
- Test invalid input validation (422)
- Test not found cases (404)
- Test server errors (500)
- **Specific Endpoint Tests:**
- `GET /api/nfo/{serie_id}/check`: Test existing/missing NFO
- `POST /api/nfo/{serie_id}/create`: Test creation, duplicate, errors
- `PUT /api/nfo/{serie_id}/update`: Test update, not found
- `GET /api/nfo/{serie_id}/content`: Test content retrieval, XML format
- `POST /api/nfo/batch/create`: Test batch processing, partial failures
- `GET /api/nfo/missing`: Test filtering, pagination
- **Integration Tests:**
- Test with mocked NFOService
- Test concurrent requests
- Test rate limiting if applicable
- **API Documentation:**
- Verify OpenAPI schema generation
- Test example requests/responses
**Files to Create:**
- `src/server/api/nfo.py`
- `src/server/models/nfo.py`
- `tests/api/test_nfo_endpoints.py`
- `tests/api/test_nfo_validation.py`
**Files to Modify:**
- [src/server/fastapi_app.py](../src/server/fastapi_app.py)
---
#### Task 6: Add NFO UI Features
**Priority:** Medium
**Estimated Time:** 4-5 hours
Add UI components for NFO management in the web interface.
**Implementation Steps:**
1. **Add NFO and Media Status Indicators**
- Show NFO status badge on series cards
- Show media file status (poster, logo, fanart) with icons
- Green check if NFO and all media exist
- Yellow warning if NFO exists but missing media
- Orange warning if missing NFO
- Red error if scraping failed
- Individual icons for each media file (poster, logo, fanart)
2. **Add NFO and Media Management Actions**
- "Create NFO" button on series without it (downloads media too)
- "Download Media" button for missing poster/logo/fanart
- "View NFO" button to display content
- "View Media" button to preview poster/logo/fanart
- "Refresh NFO" button to update from TMDB (re-download media)
- Batch "Create Missing NFOs" action
- Batch "Download Missing Media" action
3. **Create NFO Status Page** (`src/server/web/templates/nfo_status.html`)
- List all series with NFO status
- Filter: All / With NFO / Without NFO
- Bulk actions
- Search functionality
4. **Add JavaScript Handlers** (`src/server/web/static/js/nfo-manager.js`)
- API calls for NFO operations
- Progress tracking during creation
- Success/error notifications
- Real-time status updates via WebSocket
**Acceptance Criteria:**
- [ ] NFO status visible on series cards
- [ ] Can create NFO from UI
- [ ] Can view NFO content in modal
- [ ] Batch operations work
- [ ] WebSocket updates for progress
- [ ] Mobile responsive
- [ ] Follows Fluent UI design
- [ ] Frontend tests pass
- [ ] Manual UI testing documented
**Testing Requirements:**
- **Frontend Integration Tests:**
- Test NFO status badge displays correctly
- Test "Create NFO" button functionality
- Test "View NFO" modal opens and displays content
- Test "Refresh NFO" button
- Test batch create action
- Test WebSocket progress updates
- Mock API responses for all operations
- **JavaScript Unit Tests:**
- Test API call functions
- Test success/error notification handling
- Test progress update logic
- Test filtering functionality
- **UI/UX Tests:**
- Test responsive design on mobile viewport
- Test loading states
- Test error states
- Test accessibility (keyboard navigation, screen readers)
- **Manual Testing Checklist:**
- Create checklist for manual UI testing
- Test all user flows
- Test edge cases (slow network, errors)
- Browser compatibility (Chrome, Firefox, Safari, Edge)
**Files to Create:**
- `src/server/web/templates/nfo_status.html`
- `src/server/web/static/js/nfo-manager.js`
- `src/server/web/static/css/components/nfo-status.css`
- `tests/frontend/test_nfo_ui.py`
- `docs/NFO_UI_TESTING.md` (manual testing guide)
**Files to Modify:**
- [src/server/web/templates/index.html](../src/server/web/templates/index.html)
- [src/server/web/static/js/app.js](../src/server/web/static/js/app.js)
- [src/server/web/static/css/main.css](../src/server/web/static/css/main.css)
---
#### Task 7: Add NFO Configuration Settings
**Priority:** Low
**Estimated Time:** 2 hours
Add NFO configuration options to the settings UI.
**Implementation Steps:**
1. **Add NFO Settings Section** ([src/server/web/templates/settings.html](../src/server/web/templates/settings.html))
```
NFO Metadata Settings:
- TMDB API Key [text input] [required]
- Auto-create NFO files [checkbox] [default: true]
- Update NFO on rescan [checkbox] [default: false]
- Preferred language for metadata [dropdown] [default: German]
Media Download Settings:
- Download poster.jpg [checkbox] [default: true]
- Download logo.png [checkbox] [default: true]
- Download fanart.jpg [checkbox] [default: true]
- Image quality [dropdown: original/w500] [default: original]
- Overwrite existing media [checkbox] [default: false]
```
2. **Update Config Models** ([src/server/models/config.py](../src/server/models/config.py))
- Add NFOConfig section
- Add validation
3. **Add Config API Support** ([src/server/api/config.py](../src/server/api/config.py))
- Handle NFO config updates
- Validate TMDB API key on save
**Acceptance Criteria:**
- [ ] Settings UI has NFO section
- [ ] Config saves and loads correctly
- [ ] TMDB API key validated
- [ ] Settings affect NFO creation behavior
- [ ] Configuration tests pass
**Testing Requirements:**
- **Config Model Tests:**
- Test NFOConfig validation
- Test TMDB API key format validation
- Test required fields
- Test default values
- Test serialization/deserialization
- **Config API Tests:**
- Test saving NFO config
- Test loading NFO config
- Test TMDB API key validation endpoint
- Test invalid API key rejection
- Test config update affects service behavior
- **Integration Tests:**
- Test config changes are persisted
- Test config loaded on app startup
- Test NFO service respects config settings
- **UI Tests:**
- Test settings form submission
- Test validation error display
- Test success notifications
**Files to Modify:**
- [src/server/web/templates/settings.html](../src/server/web/templates/settings.html)
- [src/server/models/config.py](../src/server/models/config.py)
- [src/server/api/config.py](../src/server/api/config.py)
- `tests/unit/test_config_models.py`
- `tests/api/test_config_endpoints.py`
---
#### Task 8: Add Database Support for NFO Status
**Priority:** Medium
**Estimated Time:** 2-3 hours
Track NFO file status in the database.
**Implementation Steps:**
1. **Add NFO Fields to Database Models** ([src/server/database/models.py](../src/server/database/models.py))
```python
class AnimeSeries:
# Add fields:
has_nfo: bool = False
nfo_created_at: Optional[datetime] = None
nfo_updated_at: Optional[datetime] = None
tmdb_id: Optional[int] = None
tvdb_id: Optional[int] = None
```
2. **Update Services** ([src/server/services/anime_service.py](../src/server/services/anime_service.py))
- Update NFO status after creation
- Query series by NFO status
- Track TMDB/TVDB IDs
**Acceptance Criteria:**
- [ ] Database schema updated (SQLAlchemy will auto-create columns)
- [ ] NFO status tracked in DB
- [ ] Queries for missing NFOs work
- [ ] Backward compatible with existing data
- [ ] Database tests pass
**Testing Requirements:**
- **Model Tests:**
- Test new fields default values
- Test NFO status persistence
- Test TMDB/TVDB ID storage
- Test datetime fields
- Test nullable constraints
- **Service Tests:**
- Test updating NFO status after creation
- Test querying series by NFO status
- Test querying series without NFO
- Test TMDB/TVDB ID queries
- Mock database operations
- **Integration Tests:**
- Test database queries return correct results
- Test filter by has_nfo=True/False
- Test ordering by nfo_created_at
- Test join queries if applicable
- **Backward Compatibility Tests:**
- Test loading existing series without NFO fields
- Test default values for existing records
- Test queries work with mixed data
**Files to Modify:**
- [src/server/database/models.py](../src/server/database/models.py)
- [src/server/services/anime_service.py](../src/server/services/anime_service.py)
- `tests/unit/test_database_models.py`
- `tests/unit/test_anime_service.py`
- `tests/integration/test_nfo_database.py`
**Note:** No manual migration needed - SQLAlchemy will handle new columns automatically.
---
#### Task 9: Documentation and Testing
**Priority:** High
**Estimated Time:** 3-4 hours
Document NFO features and ensure comprehensive test coverage.
**Implementation Steps:**
1. **Update Documentation:**
- Add NFO section to [docs/API.md](../docs/API.md)
- Document NFO endpoints
- Add configuration guide to [docs/CONFIGURATION.md](../docs/CONFIGURATION.md)
- Update [README.md](../README.md) with NFO features
- Add troubleshooting section
2. **Create Integration Tests:**
- Test complete NFO creation workflow
- Test download with NFO check
- Test batch NFO creation
- Test UI interactions
3. **Add Performance Tests:**
- Test TMDB API rate limiting
- Test concurrent NFO creation
- Measure impact on download flow
**Acceptance Criteria:**
- [ ] All documentation updated
- [ ] Test coverage > 80%
- [ ] Integration tests pass
- [ ] Performance benchmarks documented
- [ ] Troubleshooting guide complete
**Files to Modify:**
- [docs/API.md](../docs/API.md)
- [docs/CONFIGURATION.md](../docs/CONFIGURATION.md)
- [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md)
- [README.md](../README.md)
**Files to Create:**
- `tests/integration/test_nfo_workflow.py`
- `tests/performance/test_nfo_performance.py`
- `docs/NFO_GUIDE.md`
---
### 📋 NFO Feature Summary
**Overview:**
These tasks integrate tvshow.nfo metadata file creation into the Aniworld download manager using the external scraper library and TMDB API. Before downloading episodes, the system will check if tvshow.nfo exists in the series folder, and if not (and auto-create is enabled), it will scrape TMDB to create the metadata file.
**Key Benefits:**
- Proper media library metadata for Kodi/Plex/Jellyfin
- Better organization and presentation
- Enhanced search and discovery
- Automatic metadata maintenance
**Technical Approach:**
1. Copy and adapt code from `/home/lukas/Volume/repo/scraper/` repository
2. Integrate TMDB API client (adapted from scraper's tmdb_client.py)
3. Integrate NFO XML generation (adapted from scraper's xml_utils.py)
4. Add NFO checking to download pre-flight checks
5. Use TMDB API to search and fetch series metadata
6. Generate tvshow.nfo with proper Kodi/XBMC format
7. Track NFO status in database
8. Provide UI for manual NFO management
**Dependencies:**
- Code reference: `/home/lukas/Volume/repo/scraper/` (copy and adapt, not as library)
- TMDB API access (requires API key)
- Additional Python packages:
- requests (for TMDB API and image downloads)
- lxml (for XML generation)
- Pillow (for image validation and processing)
**Key Files to Reference from Scraper:**
- API Client: `/home/lukas/Volume/repo/scraper/src/scraper/api/tmdb_client.py`
- Metadata Service: `/home/lukas/Volume/repo/scraper/src/scraper/services/metadata_service.py`
- Asset Service: `/home/lukas/Volume/repo/scraper/src/scraper/services/asset_service.py`
- XML Utils: `/home/lukas/Volume/repo/scraper/src/scraper/utils/xml_utils.py`
- Models: `/home/lukas/Volume/repo/scraper/src/scraper/models/tvshow.py`
- Example NFO: `/home/lukas/Volume/repo/scraper/tvshow.nfo`
- Example Media: Check existing series folders for poster.jpg, logo.png, fanart.jpg examples
**Estimated Total Time:** 25-30 hours
**Priority Order:**
1. Task 1-3: Core NFO support and scraper integration (High)
2. Task 4: Download flow integration (High)
3. Task 8: Database support (Medium)
4. Task 5: API endpoints (Medium)
5. Task 6: UI features (Medium)
6. Task 7: Configuration (Low)
7. Task 9: Documentation and testing (High)
---