File Input

Dynamically play MP4, TS files, or static images (JPG/PNG) via API calls

Features

  • Dynamic Playback: Creates file input nodes on-demand via API calls

  • Format Support: Automatically detects and plays MP4 files (TS support planned)

  • Progress Tracking: Real-time playback progress with duration and position

  • API Control: RESTful endpoints for play, stop, and status operations

  • Stream Mapping: Flexible output stream configuration

  • Error Handling: Graceful handling of file access errors from Norsk container

Component Configuration

Option Description Required

id

A unique identifier for the component instance

✓

displayName

The name shown in the Studio UI of this component

✓

sourceName

Source name for the output streams (default: "file-source")

✗

initialFilename

File to start playing automatically on component startup

✗

initialLoop

Whether to loop the initial file continuously

✗

initialStart

The initial playback state (default: "playing")

✗

initialOffsetMs

Optional initial offset in milliseconds to start playback from

✗

captureSchedule

For TS files carrying EIT: also capture the future schedule, not just now/next. The full schedule can be large, so this defaults to off. (default: false)

✗

streamMappings

Configure which streams to accept from this input

✗

notes

Additional notes about this component

✗

API Endpoints

The component provides the following REST API endpoints for dynamic control:

POST /play

Starts playback of a specified file.

Request Body:

{
  "filePath": "/path/to/file.mp4"
}

Response: - 200 OK: Playback started successfully - 400 Bad Request: Invalid request (missing filePath or already playing) - 500 Internal Server Error: Failed to start playback

POST /stop

Stops current playback and cleans up resources.

Response: - 200 OK: Playback stopped successfully - 500 Internal Server Error: Failed to stop playback

GET /status

Returns the current playback status and state.

Response:

{
  "status": "idle|playing|stopping|error",
  "currentFile": "/path/to/current/file.mp4",
  "progress": 45.2,
  "duration": 120.5,
  "position": 54.4,
  "error": "Error message if status is error"
}

Usage Examples

Starting Playback

curl -X POST http://studio-url/api/components/my-file-input/play \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/media/videos/sample.mp4"}'

Checking Status

curl http://studio-url/api/components/my-file-input/status

Stopping Playback

curl -X POST http://studio-url/api/components/my-file-input/stop

File Requirements

  • Files must be accessible to the Norsk container (not the Studio container)

  • Use absolute file paths

  • Supported formats: MP4 (TS support planned)

  • Files are automatically cleaned up after playback completion

Behavior

  • Startup: Component starts in idle state with no active file

  • Playback: Creates appropriate file input node (fileMp4 for .mp4 files)

  • Progress: Updates progress every second during playback

  • Completion: Automatically cleans up and returns to idle state

  • Error Recovery: Failed operations set component to error state with details

Stream Output

The component produces audio and video streams according to the configured stream mappings. By default, it creates:

  • Video stream: sourceName / program 1 / stream 256 / rendition "default"

  • Audio stream: sourceName / program 1 / stream 257 / rendition "default"

Stream mappings can be customized to route outputs to different destinations or apply filtering.