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

{
  "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)

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

Error Responses

400 Bad Request

{
  "error": "No image file provided"
}

404 Not Found

{
  "error": "Original content not found: image.jpg"
}

500 Internal Server Error

{
  "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

# 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

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