# 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`