Files
Jellyfin-Freebox/CLAUDE.md
T
stilobique b1ca2a7cff
CI / Release Gitea (push) Successful in 32s
CI / Vérifications et paquet (push) Successful in 47s
Refactoring: move all apps inside a sub folder
2026-11-08 14:28:28 +01:00

64 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project
A Jellyfin client for the Freebox Player (Revolution), written in pure QML (no C++). The app runs inside the Freebox's QML runtime via the `fbx.application` module, The UI follows the Jellyfin Android TV app's flow and conventions. UI text is in French.
## Layout
- `app/` — the application itself, the only directory served to / packaged for the Player (`manifest.json`, `Jellyfin.qml`, `icon.png`, `Components/`, `Core/`, `Shared/`, `Views/`, plus the QtCreator project `Jellyfin.fbxproject`). Paths in the Architecture section are relative to `app/`.
- `src/freebox_jellyfin/` — Python dev tooling; `tools/preview.qml` — desktop preview wrapper; `dist/`, `deploy.log` — generated at the repo root.
## Build / run
There is no build system or test suite.
**Local preview on the PC** (no Freebox needed): `fbx.application` from [libfbxqml](https://github.com/fbx/libfbxqml) is pure QML (a fullscreen `Window` scaled to a 720p virtual height), so the app runs with Qt 5's `qmlscene`.
- Prerequisites: `sudo apt install qmlscene qml-module-qtmultimedia qtdeclarative5-dev-tools`, and libfbxqml cloned next to the repo (`../libfbxqml`, override with `LIBFBXQML=`).
- Dev tooling is the Python package `freebox_jellyfin` (`src/freebox_jellyfin/`, uv project, Python 3.14, stdlib only): `uv sync`, then `uv run freebox-jellyfin <preview|check|package|deploy>` (also `python -m freebox_jellyfin`). `project.py` locates `REPO_DIR` (dir with `pyproject.toml` + `app/manifest.json`, from cwd then from the module) and `APP_DIR` (`app/`), libfbxqml and qmlscene. `tools/` now only holds `preview.qml`.
- `uv run freebox-jellyfin preview` — 1280×720 window via `tools/preview.qml`; `--fullscreen` runs `app/Jellyfin.qml` as the box would.
- `QT_QPA_PLATFORM=offscreen uv run freebox-jellyfin preview` — headless run, useful to catch QML warnings.
- HTTPS on the PC works with the system `qmlscene` (Qt 5.15 + OpenSSL 3). PyQt5 wheels from pip bundle a Qt built for OpenSSL 1.x and cannot do TLS here.
- Lint: `cd app && qmllint Jellyfin.qml Components/*.qml Core/*.qml Shared/*.qml Views/*.qml`
- `uv run freebox-jellyfin check` — serves `app/` over HTTP and loads it with `qmlscene` (offscreen, software renderer) like the box does; fails on any Qt warning not coming from libfbxqml. Run it after touching imports, `qmldir` files or singletons.
- **Reproduce the box's loading mode**: the Player loads the app over HTTP, which behaves differently from local files (see constraints below). Check with `python3 -m http.server 8765 --directory app` then `QT_QPA_PLATFORM=offscreen qmlscene -I ../libfbxqml http://127.0.0.1:8765/Jellyfin.qml` — it must print no warnings.
- The desktop has Qt 5.15 while the box targets QtQuick 2.5: code that runs locally can still use APIs too new for the box.
**CI** (`.gitea/workflows/ci.yml`, Gitea Actions on the `ubuntu-latest` runner image): installs uv (pinned 0.12.9, which fetches Python 3.14) and on every push/PR runs `uv run --locked freebox-jellyfin package` (manifest + qmllint + archive) and `… check`; package uploaded as artifact (`upload-artifact@v3`/`download-artifact@v3`: v4 only works on recent Gitea versions). On tag `vX.Y.Z` matching `manifest.json` `version`, creates a Gitea release with the package attached (API calls with the job's `GITHUB_TOKEN`). Verified locally by replaying the `check` job's steps in a clean `ubuntu:24.04` container; the release job has not run yet.
**FreeStore package**: `freebox-jellyfin package` → `dist/<identifier>-<version>.tar.gz` (gitignored). Replicates the QtCreator plugin's "Make FreeStore Package": same file selection as `Jellyfin.fbxproject` (QML/JS/images/fonts/`qmldir`/`manifest.json` under `app/`, hidden dirs excluded; archive paths relative to `app/`), manifest checks (identifier `\w+(\.\w+)+`, `version` x.y.z equal to `Session.clientVersion`, entry-point files present), `qmllint` on all sources, ustar tar with directory entries, gzipped. Upload is manual on the FreeFactory console (http://factory.free.fr), followed by Free's review.
**Deploying a test build to the Freebox**: `freebox-jellyfin deploy` (`src/freebox_jellyfin/deploy.py`; Player must be in developer mode). It discovers the Player via SSDP (`fbx:devel`) or takes `--box <IP>`, serves `app/` over HTTP, calls JSON-RPC `debug_qml_app` on `http://<box>/pub/devel`, and streams the app's stdout/stderr until it exits. `--server <host>` and `--user name[:password]` (both repeatable) serve a virtual `dev-config.json` next to the app; at startup `Session.loadDevConfig()` adds each listed server and stores users in `Session.devUsers`, which `UserSelectView` merges with public users (one-click sign-in when a password is given; never log passwords) (only when the app is loaded over HTTP; 404 otherwise, ignored) — the workaround for the lack of persistence in dev mode. Output is also written to `deploy.log` (repo root, gitignored, overwritten each run) — read it to diagnose on-box failures. The Player fetches files lazily from that HTTP server, so the script must keep running while the app is in use. This replicates the "Run" of the official QtCreator plugin, whose own setup is:
- SDK setup: https://dev.freebox.fr/sdk/player.html (Windows: https://github.com/fbx/freebox-qtcreator-plugin/issues/8)
- Open `app/Jellyfin.fbxproject` in QtCreator with the Freebox plugin; the run target deploys to a Freebox Player on the LAN (configured in `Jellyfin.fbxproject.user`, which is machine-specific).
- `Jellyfin.fbxproject` packages every QML/JS/image/font/`qmldir` file under `app/` plus `manifest.json` — new files are picked up automatically.
## Architecture
- `Jellyfin.qml` — root `Application`: logo panel (1/3) + `Navigator` (2/3), owns the single `Session` instance. The logo panel hides when the current page sets `fullscreen: true` (catalog and player screens).
- `Core/Navigator.qml` — screen stack on a `Loader`. `push("Name")` loads `Views/NameView.qml`; also `replace`, `pop`, `reset`. Every view gets `navigator` and `session` injected, plus any props passed to `push`. Remote Back/Escape pops; at the root it propagates (exits app). After loading, focus goes to the view's `initialFocus`. `openItem(item)` routes a catalog item to `Library` / `Season` / `Details`.
- `Core/Session.qml` — Jellyfin API client over `XMLHttpRequest` (`_request()`: JSON, `Authorization: MediaBrowser …` header with `Token` once signed in, per-request timeout via a dynamically created `Timer` since Qt 5.5 XHR has none). Holds saved servers (`ListModel`, persisted through `fbx.application` `Settings` — works on the box only; on the PC `App is not defined` warnings are expected and nothing persists), `currentServer`, `currentUser`, `accessToken`. Endpoints: `/System/Info/Public` (server probe: all candidates in parallel, first success in priority order wins so a slow first TLS handshake doesn't fall back to http), `/Users/Public`, `/Users/AuthenticateByName`, `/Sessions/Logout`, `/QuickConnect/*`; catalog `/UserViews`, `/UserItems/Resume`, `/Items/Latest`, `/Items`, `/Shows/{id}/Seasons|Episodes`; playback `/Items/{id}/PlaybackInfo` and `/Sessions/Playing[/Progress|/Stopped]`. API items are flattened by `_toItem()` (no `index` key: reserved role name in `ListModel`). Image URLs via `posterUrl()` / `thumbUrl()` / `backdropUrl()`. Async functions call `callback(error, result)` with `error` a user-facing French message. Every public callback is wrapped by `_guard()`; `cancel()` (called by views on destruction) drops pending callbacks and stops Quick Connect polling.
- `Core/DeviceProfile.js` — what the Freebox Player can play, sent in `PlaybackInfo`: direct play H.264 only (the Revolution has no HEVC), otherwise HLS transcode. Text subtitles must stay declared `External` and `SubtitleStreamIndex: -1` sent, or Jellyfin transcodes to burn them in (`SubtitleCodecNotSupported`).
- `Components/` — reusable widgets, listed in `Components/qmldir`. `MediaCard` / `MediaRow` for catalog cards and horizontal rows. `VideoSurface` wraps the player: it tries the Freebox native `fbx.media` `VideoPlayer` then QtMultimedia `Video`, both created with `Qt.createQmlObject` so a missing module doesn't break loading; it polls the backend and exposes `position`/`duration` (ms) and `playerState`. **On the box, `fbx.media` is not installed: QtMultimedia is what plays** (verified: HLS transcode, seek/resume, pause, positions in ms). The fbx branch is kept as a fallback but is untested.
- `Shared/` — `Theme` singleton (colors, spacing, fonts, card sizes; the only type in `Shared/qmldir`), `Remote.js` (`isAccept`/`isBack` key mapping) and `Format.js` (durations, ticks↔ms, card labels), both `.pragma library`.
- `Views/` — one screen per file, each rooted in `Page` (title/subtitle header + content area). Flow: `ServerSelect` → `ServerAdd` → `UserSelect` → `Login` (password or Quick Connect) → `Home` (rows: Reprendre, Mes médias, latest per library) → `Library` (paged poster grid) / `Details` (movie, episode, or series with seasons) → `Season` (episodes) → `Player` (`PlayerView` is a plain `FocusScope`, not a `Page`).
## Platform constraints
- Target is QtQuick 2.5 (Qt 5.5 era): **ES5 JavaScript only** (`var`, `function`; no `let`/`const`/arrow functions) and no QtQuick.Controls.
- Input is a TV remote: navigation uses `KeyNavigation` + explicit focus. On a `ListView`, set `KeyNavigation.priority: KeyNavigation.AfterItem` so the list handles arrows itself and only hands off at its ends.
- The box's virtual keyboard lacks `:` (and likely `/`): never require typing a URL scheme or `host:port`. Server entry takes host + optional numeric port; `Session.serverCandidates()` derives the URLs to probe (https, http:8096, https:8920, http).
- **No persistent storage when launched via `freebox-jellyfin deploy`** (dev mode, app not installed), even with a Freebox profile open (`profileId=1`): `Settings` saves fail with `profiles.application_data_set` "internal json-rpc error", and `QtQuick.LocalStorage` exists but cannot create `/var/lib/databases/fbxqmltv/Databases`. Expected to work once installed as a FreeStore package (unverified). Code must keep working with nothing persisted.
- The box's native `fbx.application` `Application` differs from libfbxqml's: e.g. it has `profileId` but no `identifier`. Don't rely on libfbxqml-only properties; guard with `typeof`.
- In bindings, guard `page.session`/`page.navigator` against null: they are injected after bindings are first evaluated.
- **HTTP loading rules** (the box fetches files over HTTP, so directories can't be listed):
- every imported directory needs a `qmldir` listing all its types (`Core/`, `Components/`, `Shared/`); a missing one gives "X is not a type" only on the box;
- a singleton must not live in the same directory as the components that use it, and a directory must hold at most one singleton — otherwise "Cyclic dependency detected". Put helpers in `.pragma library` JS files instead of new singletons;
- no `import "."` self-imports.
- **Playback reporting must never clobber the server's resume point**: `PlayerView` reports start/progress/stop only once playback actually started *and* the resume position was reached, and never with position 0. (A failed playback reporting a stop at 0 wipes the user's resume position.)
- Don't disable (`enabled: false`) a focused control during loading — it loses focus and the remote stops responding; guard with a `busy` flag instead.