Repository navigation
MediaTrail 0.25.5
MediaTrail 0.25.5 is a self-hosted media tracker image. The visible name is MediaTrail. Inside the image the application path is still /yamtrack and the Python package name is still yamtrack, so existing volume paths and imports stay the same.
Image: ghcr.io/aicon/mediatrail:0.25.5
latest points at this build. The repository and the package are private.
Version numbers continue from 0.25.3 in small steps. This release is 0.25.5. The About page and GET /api/v1/info/ report the VERSION value baked into the image.
Run
docker-compose.local.yml starts one service, mediatrail, and publishes port 8000. It does not start a Redis container. Mount ./db at /yamtrack/db. Set SECRET and TZ in the runtime environment.
docker-compose.yml and docker-compose.postgres.yml are the upstream examples. They are not this image.
Provider keys, including a Gemini key, are runtime settings. They are not Docker build arguments and they are not copied into the image. .env files are excluded from the build context.
Process layout
The runtime is Python 3.12 on Alpine. Supervisord runs Redis, nginx, gunicorn, and Celery in one container. nginx listens on port 8000, with an IPv6 listen line in the generated config. The process user is abc, so PUID and PGID can be mapped at start. The image healthcheck requests http://127.0.0.1:8000/health/.
The preview API dependencies (Django REST framework and drf-spectacular) are installed in the image after the locked sync. GET /api/v1/info/ returns version, debug, frontend URL, language, and timezone.
Redis
Redis runs inside the image. It binds 127.0.0.1:6379 with protected mode on. AOF is enabled and the data directory is /yamtrack/db/redis, on the same volume as the application database. The image sets REDIS_URL=redis://127.0.0.1:6379.
Set REDIS_URL only when cache and Celery should use a Redis server outside this container. CELERY_REDIS_URL defaults to REDIS_URL.
Now Watching
The home page shows a live playback strip while a client is reporting playback. The strip refreshes every 10 seconds from /now-watching/.
The strip shows a blurred backdrop, the poster, a status badge, and the start time. The badge is NOW WATCHING or PAUSED. It is a status label only. MediaTrail does not send pause or resume commands to the player. Playback stays in the client (Nuvio, Jellyfin, Stremio, and the rest).
The poster and the title open the media page. A movie shows title and year. An episode shows the series title and year, a season/episode code, and the episode title when one exists. Episode names come from TMDB in the configured language, with an English request when the local name is only a placeholder such as "Episode 21". If no real title exists, the strip shows the season/episode code only.
Progress is floor(100 * position / duration) when the duration is known. The strip then shows the percent, the time left, a soft elapsed wash, and a bottom progress bar at the same percent.
The top-right control dismisses a stuck strip. In 0.25.5 that control is a centered icon inside the square button. Dismiss deletes the live row only. It does not change watch history or tracked status. A later progress report can show the strip again while playback is still going.
Stale rows are removed without touching history:
watchingwith no update for 3 minutes (LIVE_PLAYBACK_WATCHING_STALE_SECONDS)pausedwith no update for 10 minutes (LIVE_PLAYBACK_PAUSED_STALE_SECONDS)
Progress and start events refresh the timestamp and set the status back to watching.
Playback API
Clients report playback on the preview API:
PUT /api/v1/playback/writes a watching or paused live rowGET /api/v1/playback/reads the current live rowGET /api/v1/playback/now/returns 204 when nothing is liveDELETE /api/v1/playback/clears one title without completing itDELETE /api/v1/playback/now/clears every live row for the user
start and progress with a position above zero mark the row watching. pause keeps the strip and marks it paused. stop below the watched threshold clears the live row and does not write history. stop at or above the threshold clears the live row and writes one history row. A repeated stop does not write a second history row. Clearing a live row never changes episode or movie history.
This release
0.25.5 centers the Now Watching dismiss icon in its button and publishes that build as ghcr.io/aicon/mediatrail:0.25.5.