djsundog/ffplayout
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
36526a15c7
ffplayout/docs/api.md
jb-alvarado 36526a15c7 make paths optional
2023-09-12 20:29:29 +02:00

9.1 KiB
Raw Blame History

Possible endpoints

Run the API thru the systemd service, or like:

ffpapi -l 127.0.0.1:8787

For all endpoints an (Bearer) authentication is required.
{id} represent the channel id, and at default is 1.

User Handling

Login

curl -X POST http://127.0.0.1:8787/auth/login/ -H "Content-Type: application/json" \
-d '{ "username": "<USER>", "password": "<PASS>" }'

Response:

{
    "id": 1,
    "mail": "user@example.org",
    "username": "<USER>",
    "token": "<TOKEN>"
}

From here on all request must contain the authorization header:
"Authorization: Bearer <TOKEN>"

Get current User

curl -X GET 'http://127.0.0.1:8787/api/user' -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Update current User

curl -X PUT http://127.0.0.1:8787/api/user/1 -H 'Content-Type: application/json' \
-d '{"mail": "<MAIL>", "password": "<PASS>"}' -H 'Authorization: Bearer <TOKEN>'

Add User

curl -X POST 'http://127.0.0.1:8787/api/user/' -H 'Content-Type: application/json' \
-d '{"mail": "<MAIL>", "username": "<USER>", "password": "<PASS>", "role_id": 1, "channel_id": 1}' \
-H 'Authorization: Bearer <TOKEN>'

ffpapi Settings

Get Settings from Channel

curl -X GET http://127.0.0.1:8787/api/channel/1 -H "Authorization: Bearer <TOKEN>"

Response:

{
    "id": 1,
    "name": "Channel 1",
    "preview_url": "http://localhost/live/preview.m3u8",
    "config_path": "/etc/ffplayout/ffplayout.yml",
    "extra_extensions": "jpg,jpeg,png",
    "service": "ffplayout.service",
    "utc_offset": "+120"
}

Get settings from all Channels

curl -X GET http://127.0.0.1:8787/api/channels -H "Authorization: Bearer <TOKEN>"

Update Channel

curl -X PATCH http://127.0.0.1:8787/api/channel/1 -H "Content-Type: application/json" \
-d '{ "id": 1, "name": "Channel 1", "preview_url": "http://localhost/live/stream.m3u8", "config_path": "/etc/ffplayout/ffplayout.yml", "extra_extensions": "jpg,jpeg,png"}' \
-H "Authorization: Bearer <TOKEN>"

Create new Channel

curl -X POST http://127.0.0.1:8787/api/channel/ -H "Content-Type: application/json" \
-d '{ "name": "Channel 2", "preview_url": "http://localhost/live/channel2.m3u8", "config_path": "/etc/ffplayout/channel2.yml", "extra_extensions": "jpg,jpeg,png", "service": "ffplayout@channel2.service" }' \
-H "Authorization: Bearer <TOKEN>"

Delete Channel

curl -X DELETE http://127.0.0.1:8787/api/channel/2 -H "Authorization: Bearer <TOKEN>"

ffplayout Config

Get Config

curl -X GET http://127.0.0.1:8787/api/playout/config/1 -H 'Authorization: Bearer <TOKEN>'

Response is a JSON object from the ffplayout.yml

Update Config

curl -X PUT http://127.0.0.1:8787/api/playout/config/1 -H "Content-Type: application/json" \
-d { <CONFIG DATA> } -H 'Authorization: Bearer <TOKEN>'

Text Presets

Text presets are made for sending text messages to the ffplayout engine, to overlay them as a lower third.

Get all Presets

curl -X GET http://127.0.0.1:8787/api/presets/ -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Update Preset

curl -X PUT http://127.0.0.1:8787/api/presets/1 -H 'Content-Type: application/json' \
-d '{ "name": "<PRESET NAME>", "text": "<TEXT>", "x": "<X>", "y": "<Y>", "fontsize": 24, "line_spacing": 4, "fontcolor": "#ffffff", "box": 1, "boxcolor": "#000000", "boxborderw": 4, "alpha": 1.0, "channel_id": 1 }' \
-H 'Authorization: Bearer <TOKEN>'

Add new Preset

curl -X POST http://127.0.0.1:8787/api/presets/ -H 'Content-Type: application/json' \
-d '{ "name": "<PRESET NAME>", "text": "TEXT>", "x": "<X>", "y": "<Y>", "fontsize": 24, "line_spacing": 4, "fontcolor": "#ffffff", "box": 1, "boxcolor": "#000000", "boxborderw": 4, "alpha": 1.0, "channel_id": 1 }' \
-H 'Authorization: Bearer <TOKEN>'

Delete Preset

curl -X DELETE http://127.0.0.1:8787/api/presets/1 -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

ffplayout controlling

here we communicate with the engine for:

  • jump to last or next clip
  • reset playlist state
  • get infos about current, next, last clip
  • send text to the engine, for overlaying it (as lower third etc.)

Send Text to ffplayout

curl -X POST http://127.0.0.1:8787/api/control/1/text/ \
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>' \
-d '{"text": "Hello from ffplayout", "x": "(w-text_w)/2", "y": "(h-text_h)/2", fontsize": "24", "line_spacing": "4", "fontcolor": "#ffffff", "box": "1", "boxcolor": "#000000", "boxborderw": "4", "alpha": "1.0"}'

Control Playout

  • next
  • back
  • reset
curl -X POST http://127.0.0.1:8787/api/control/1/playout/ -H 'Content-Type: application/json'
-d '{ "command": "reset" }' -H 'Authorization: Bearer <TOKEN>'

Get current Clip

curl -X GET http://127.0.0.1:8787/api/control/1/media/current
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'

Response:

{
    "jsonrpc": "2.0",
    "result": {
      "current_media": {
        "category": "",
        "duration": 154.2,
        "out": 154.2,
        "seek": 0.0,
        "source": "/opt/tv-media/clip.mp4"
      },
      "index": 39,
      "play_mode": "playlist",
      "played_sec": 67.80771999300123,
      "remaining_sec": 86.39228000699876,
      "start_sec": 24713.631999999998,
      "start_time": "06:51:53.631"
    },
    "id": 1
}

Get next Clip

curl -X GET http://127.0.0.1:8787/api/control/1/media/next/ -H 'Authorization: Bearer <TOKEN>'

Get last Clip

curl -X GET http://127.0.0.1:8787/api/control/1/media/last/
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'

ffplayout Process Control

Control ffplayout process, like:

  • start
  • stop
  • restart
  • status
curl -X POST http://127.0.0.1:8787/api/control/1/process/
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'
-d '{"command": "start"}'

ffplayout Playlist Operations

Get playlist

curl -X GET http://127.0.0.1:8787/api/playlist/1?date=2022-06-20
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'

Save playlist

curl -X POST http://127.0.0.1:8787/api/playlist/1/
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'
--data "{<JSON playlist data>}"

Generate Playlist

A new playlist will be generated and response.

curl -X POST http://127.0.0.1:8787/api/playlist/1/generate/2022-06-20
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'
/// --data '{ "paths": [<list of paths>] }' # <- data is optional

Or with template:

curl -X POST http://127.0.0.1:8787/api/playlist/1/generate/2023-00-05
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'
--data '{"template": {"sources": [\
           {"start": "00:00:00", "duration": "10:00:00", "shuffle": true, "paths": ["path/1", "path/2"]}, \
           {"start": "10:00:00", "duration": "14:00:00", "shuffle": false, "paths": ["path/3", "path/4"]}]}}'

Delete Playlist

curl -X DELETE http://127.0.0.1:8787/api/playlist/1/2022-06-20
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'

Log file

Read Log Life

curl -X GET http://127.0.0.1:8787/api/log/1
-H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>'

File Operations

Get File/Folder List

curl -X POST http://127.0.0.1:8787/api/file/1/browse/ -H 'Content-Type: application/json'
-d '{ "source": "/" }' -H 'Authorization: Bearer <TOKEN>'

Create Folder

curl -X POST http://127.0.0.1:8787/api/file/1/create-folder/ -H 'Content-Type: application/json'
-d '{"source": "<FOLDER PATH>"}' -H 'Authorization: Bearer <TOKEN>'

Rename File

curl -X POST http://127.0.0.1:8787/api/file/1/rename/ -H 'Content-Type: application/json'
-d '{"source": "<SOURCE>", "target": "<TARGET>"}' -H 'Authorization: Bearer <TOKEN>'

Remove File/Folder

curl -X POST http://127.0.0.1:8787/api/file/1/remove/ -H 'Content-Type: application/json'
-d '{"source": "<SOURCE>"}' -H 'Authorization: Bearer <TOKEN>'

Upload File

curl -X PUT http://127.0.0.1:8787/api/file/1/upload/ -H 'Authorization: Bearer <TOKEN>'
-F "file=@file.mp4"

Import playlist

Import text/m3u file and convert it to a playlist lines with leading "#" will be ignore

curl -X PUT http://127.0.0.1:8787/api/file/1/import/ -H 'Authorization: Bearer <TOKEN>'
-F "file=@list.m3u"

Program info

Get program infos about given date, or current day

Examples:

  • get program from current day
curl -X GET http://127.0.0.1:8787/api/program/1/ -H 'Authorization: Bearer <TOKEN>'
  • get a program range between two dates
curl -X GET http://127.0.0.1:8787/api/program/1/?start_after=2022-11-13T12:00:00&start_before=2022-11-20T11:59:59 \
-H 'Authorization: Bearer <TOKEN>'
  • get program from give day
curl -X GET http://127.0.0.1:8787/api/program/1/?start_after=2022-11-13T10:00:00 \
-H 'Authorization: Bearer <TOKEN>'