Audio description: For developers
How Audio description is built, for anyone who wants to change it or make one like it. It is MIT, by TheMightyTRexUK, and works with plug-in API >=1.14 <2.0.
Its files
starboard-plugin.jsonapp.pysbplugin.pyDockerfileinstall.pylogo.svgrules.json, shared with the Jellyfin version and copied bytools/sync_audio_description_rules.pyCHANGELOG.mdtests/test_audio_description.py
Containers
| Container | Network | Folders | Runs as | Starts | Limits |
|---|---|---|---|---|---|
main |
lan |
data |
10001:10001 |
when_needed |
64 MB, 0.25 core |
Each image is pinned by digest in the manifest:
main:ghcr.io/themightytrex/starboard-plugin-examples@sha256:83b980f1828cdee537bcdf03702ddf6458710cba53f9009938225df430d34d9e
What Starboard calls
| Path | What it is |
|---|---|
GET /health |
Health: 200 while it can work |
GET /count |
The Audio description card (stat) |
GET /recent |
The Recently found with audio description card (list) |
POST /scan |
The Check for described titles now button |
POST /reelix |
The Check the Reelix choice now button |
GET /people |
The People who want audio description page |
GET /titles |
The Titles with audio description page |
GET /elsewhere |
The Audio description elsewhere page |
GET /audiovault |
The Search AudioVault page |
GET /youdescribe |
The Search YouDescribe page |
GET /apps |
The MovieReading and Earcatch page |
GET /play |
The Play the described track page |
POST /events |
Starboard's playback.started event |
POST /jobs/scan |
The job Check for titles with audio description |
POST /jobs/reelix |
The job Check the audio description choice in Reelix |
POST /update/before |
The update's before step, 60 seconds at most |
POST /update/after |
The update's after step, 10 seconds at most |
Jobs
scan: daily at 04:20, only in quiet hours, 20 minutes at most.reelix: when Starboard starts, 2 minutes at most.
How it works
- The container rests when idle (
start: when_needed, resting after 10 minutes). Starboard wakes it for its jobs, its buttons and its pages. Nothing runs on a timer of its own. scanreads every film and episode from Jellyfin's/Items, 200 at a time with their streams only, then every series once with its tags and year, so memory stays flat whatever the library's size. A track counts when its title, display title or comment names audio description and does not mention commentary.- It keeps
/data/result.json(the described titles: each film's Jellyfin id, name, year and track, and each series' id, year, counts and described episodes with their numbers and tracks, for Titles with audio description, which reads only this file),/data/seen.json(when each was first found, for the Recently found card) and/data/without.json(titles without a described track, for the Sources' links). reelixonly reads Reelix with the manager key Starboard gives (issue #144):GET /customformats/builtin/audio_description, or on an older ReelixGET /customformatsby name, andGET /qualityprofiles, and counts the video levels that give the format a score of more than 0. It never posts a format or puts a quality level, which Reelix allows only to an admin key, and never fails the job: it answers with what to do.- For each person activated, it sets Jellyfin's RememberAudioSelections and keeps what they had in
/data/people.json, to put back when they are deactivated. It tries Jellyfin 10.9's/Users/Configurationfirst, then 10.8's address. - After reading the library,
scantags withPOST /Items/{id}(the whole item, read withGET /Items/{id}, as Jellyfin's metadata editor saves it) only the items whose tag changes, and keeps the collection with/Collections. It skips both when Jellyfin's/Pluginslists the Jellyfin version (7a591954-9c27-4ba7-80c3-dc5f0a140692), asked at most every 10 minutes. - On
playback.started, it reads/Sessions; for each session of a chosen person playing a title whose described track is not playing, and whose app listsSetAudioStreamIndexin its supported commands, it sendsPOST /Sessions/{id}/Commandwith that command and the track'sIndex. Each start is handled once. - Check for described titles now runs the scan in the background, because a button must answer in 10 seconds.
- Cards set their status with
band()fromsbplugin.py. Its before update step holds new runs and waits for one that is running.
Find out more
This page on GitHub, where the help is written.