digiserver-v2/PLAYER_EDIT_MEDIA_API.md

# Player Edit Media API

## Overview
This API allows players to upload edited media files back to the server, maintaining version history and automatically updating playlists.

## Endpoint

### POST `/api/player-edit-media`

Upload an edited media file from a player device.

**Authentication Required:** Yes (Bearer token)

**Rate Limit:** 60 requests per 60 seconds

**Content-Type:** `multipart/form-data`

## Request

### Form Data

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `image_file` | File | Yes | The edited image file |
| `metadata` | JSON String | Yes | Metadata about the edit (see below) |

### Metadata JSON Structure

```json
{
  "time_of_modification": "2025-12-05T20:30:00Z",
  "original_name": "image.jpg",
  "new_name": "image_v1.jpg",
  "version": 1,
  "user": "player_user_name"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_of_modification` | ISO 8601 DateTime | Yes | When the edit was made |
| `original_name` | String | Yes | Original filename (must exist in content) |
| `new_name` | String | Yes | New filename with version suffix |
| `version` | Integer | Yes | Version number (1, 2, 3, etc.) |
| `user` | String | No | User who made the edit |

## Response

### Success (200 OK)

```json
{
  "success": true,
  "message": "Edited media received and processed",
  "edit_id": 123,
  "version": 1,
  "new_playlist_version": 5
}
```

### Error Responses

#### 400 Bad Request
```json
{
  "error": "No image file provided"
}
```

#### 404 Not Found
```json
{
  "error": "Original content not found: image.jpg"
}
```

#### 500 Internal Server Error
```json
{
  "error": "Internal server error"
}
```

## Workflow

1. **Player edits media** - User edits an image/PDF/PPTX on the player device
2. **Player uploads** - Player sends edited file + metadata to this endpoint
3. **Server processes**:
   - Saves edited file to `/static/uploads/edited_media/<content_id>/<new_name>`
   - Saves metadata JSON to `/static/uploads/edited_media/<content_id>/<new_name>_metadata.json`
   - Replaces original file in `/static/uploads/` with edited version
   - Creates database record in `player_edit` table
   - Increments playlist version to trigger player refresh
   - Clears playlist cache
4. **Player refreshes** - Next playlist check shows updated media

## Version History

Each edit is saved with a version number:
- `image.jpg` → `image_v1.jpg` (first edit)
- `image.jpg` → `image_v2.jpg` (second edit)
- etc.

All versions are preserved in the `edited_media/<content_id>/` folder.

## Example cURL Request

```bash
# First, authenticate to get token
TOKEN=$(curl -X POST http://server/api/auth/authenticate \
  -H "Content-Type: application/json" \
  -d '{"hostname": "player-1", "password": "password123"}' \
  | jq -r '.token')

# Upload edited media
curl -X POST http://server/api/player-edit-media \
  -H "Authorization: Bearer $TOKEN" \
  -F "image_file=@edited_image_v1.jpg" \
  -F 'metadata={"time_of_modification":"2025-12-05T20:30:00Z","original_name":"image.jpg","new_name":"image_v1.jpg","version":1,"user":"john"}'
```

## Python Example

```python
import requests
import json

# Authenticate
auth_response = requests.post(
    'http://server/api/auth/authenticate',
    json={'hostname': 'player-1', 'password': 'password123'}
)
token = auth_response.json()['token']

# Prepare metadata
metadata = {
    'time_of_modification': '2025-12-05T20:30:00Z',
    'original_name': 'image.jpg',
    'new_name': 'image_v1.jpg',
    'version': 1,
    'user': 'john'
}

# Upload edited file
with open('edited_image_v1.jpg', 'rb') as f:
    response = requests.post(
        'http://server/api/player-edit-media',
        headers={'Authorization': f'Bearer {token}'},
        files={'image_file': f},
        data={'metadata': json.dumps(metadata)}
    )

print(response.json())
```

## Database Schema

### player_edit Table

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER | Primary key |
| player_id | INTEGER | Foreign key to player |
| content_id | INTEGER | Foreign key to content |
| original_name | VARCHAR(255) | Original filename |
| new_name | VARCHAR(255) | New filename with version |
| version | INTEGER | Version number |
| user | VARCHAR(255) | User who made the edit |
| time_of_modification | DATETIME | When edit was made |
| metadata_path | VARCHAR(512) | Path to metadata JSON |
| edited_file_path | VARCHAR(512) | Path to edited file |
| created_at | DATETIME | Record creation time |

## UI Display

Edited media history is displayed on the player management page under the "Edited Media on the Player" card, showing:
- Original filename
- Version number
- Editor name
- Modification time
- Link to view edited file