alexei.dolgolyov
7c631d09f6
- Refactored index.html: Split into separate HTML (309 lines), CSS (908 lines), and JS (1,286 lines) files - Implemented media browser with folder configuration, recursive navigation, and thumbnail display - Added metadata extraction using mutagen library (title, artist, album, duration, bitrate, codec) - Implemented thumbnail generation and caching with SHA256 hash-based keys and LRU eviction - Added platform-specific file playback (os.startfile on Windows, xdg-open on Linux, open on macOS) - Implemented path validation security to prevent directory traversal attacks - Added smooth thumbnail loading with fade-in animation and loading spinner - Added i18n support for browser (English and Russian) - Updated dependencies: mutagen>=1.47.0, pillow>=10.0.0 - Added comprehensive media browser documentation to README Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
140 lines
3.9 KiB
Markdown
140 lines
3.9 KiB
Markdown
# Media Server - Development Guide
|
|
|
|
## Overview
|
|
|
|
Standalone REST API server (FastAPI) for controlling system-wide media playback on Windows, Linux, macOS, and Android.
|
|
|
|
## Running the Server
|
|
|
|
### Manual Start
|
|
|
|
```bash
|
|
python -m media_server.main
|
|
```
|
|
|
|
### Auto-Start on Boot (Windows Task Scheduler)
|
|
|
|
Run in **Administrator PowerShell** from the media-server directory:
|
|
|
|
```powershell
|
|
.\media_server\service\install_task_windows.ps1
|
|
```
|
|
|
|
To remove the scheduled task:
|
|
|
|
```powershell
|
|
Unregister-ScheduledTask -TaskName "MediaServer" -Confirm:$false
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Server Restart After Code Changes
|
|
|
|
**CRITICAL:** When making changes to backend code (Python files, API routes, service logic), the media server MUST be restarted for changes to take effect.
|
|
|
|
**When to restart:**
|
|
|
|
- Changes to any Python files (`*.py`) in the media_server directory
|
|
- Changes to API endpoints, routes, or request/response models
|
|
- Changes to service logic, callbacks, or script execution
|
|
- Changes to configuration handling or startup logic
|
|
|
|
**When restart is NOT needed:**
|
|
|
|
- Static file changes (`*.html`, `*.css`, `*.js`, `*.json`) - browser refresh is enough
|
|
- README or documentation updates
|
|
- Changes to install/service scripts (only affects new installations)
|
|
|
|
**How to restart during development:**
|
|
|
|
1. Find the running server process:
|
|
|
|
```bash
|
|
# Windows
|
|
netstat -ano | findstr :8765
|
|
|
|
# Linux/macOS
|
|
lsof -i :8765
|
|
```
|
|
|
|
2. Stop the server:
|
|
|
|
```bash
|
|
# Windows
|
|
taskkill //F //PID <process_id>
|
|
|
|
# Linux/macOS
|
|
kill <process_id>
|
|
```
|
|
|
|
3. Start the server again:
|
|
|
|
```bash
|
|
python -m media_server.main
|
|
```
|
|
|
|
**Best Practice:** Always restart the server immediately after committing backend changes to verify they work correctly before pushing.
|
|
|
|
**CRITICAL** Always check acccessibility of WebUI after server restart to ensure that server has started without issues
|
|
|
|
## Configuration
|
|
|
|
Copy `config.example.yaml` to `config.yaml` and customize.
|
|
|
|
The API token is generated on first run and displayed in the console output.
|
|
|
|
Default port: `8765`
|
|
|
|
## Internationalization (i18n)
|
|
|
|
The Web UI supports multiple languages with translations stored in separate JSON files.
|
|
|
|
### Locale Files
|
|
|
|
Translation files are located in:
|
|
- `media_server/static/locales/en.json` - English (default)
|
|
- `media_server/static/locales/ru.json` - Russian
|
|
|
|
### Maintaining Translations
|
|
|
|
**IMPORTANT:** When adding or modifying user-facing text in the Web UI:
|
|
|
|
1. **Update all locale files** - Add or update the translation key in **both** `en.json` and `ru.json`
|
|
2. **Use consistent keys** - Follow the existing key naming pattern (e.g., `section.element`, `scripts.button.save`)
|
|
3. **Test both locales** - Verify translations appear correctly by switching between EN/RU
|
|
|
|
### Adding New Text
|
|
|
|
When adding new UI elements:
|
|
|
|
1. Add the English text to `static/locales/en.json`
|
|
2. Add the Russian translation to `static/locales/ru.json`
|
|
3. In HTML: use `data-i18n="key.name"` for text content
|
|
4. In HTML: use `data-i18n-placeholder="key.name"` for input placeholders
|
|
5. In HTML: use `data-i18n-title="key.name"` for title attributes
|
|
6. In JavaScript: use `t('key.name')` or `t('key.name', {param: value})` for dynamic text
|
|
|
|
### Adding New Locales
|
|
|
|
To add support for a new language:
|
|
|
|
1. Create `media_server/static/locales/{lang_code}.json` (copy from `en.json`)
|
|
2. Translate all strings to the new language
|
|
3. Add the language code to `supportedLocales` array in `index.html`
|
|
|
|
## Versioning
|
|
|
|
Version is tracked in two files that must be kept in sync:
|
|
|
|
- `pyproject.toml` - `[project].version`
|
|
- `media_server/__init__.py` - `__version__`
|
|
|
|
When releasing a new version, update both files with the same version string.
|
|
|
|
**Important:** After making any changes, always ask the user if the version needs to be incremented.
|
|
|
|
## Git Rules
|
|
|
|
- **ALWAYS ask for user approval before committing and pushing changes.**
|
|
- When pushing, always push to all remotes: `git push origin master && git push github master`
|