Files
Jellyfin-Freebox/CLAUDE.md
T
2026-11-08 10:38:26 +01:00

41 lines
3.8 KiB
Markdown
Raw 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, so it cannot be run with a stock `qmlscene` — `import fbx.application 1.0` only resolves on the box or through the Freebox SDK. The UI follows the Jellyfin Android TV app's flow and conventions. UI text is in French.
## 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=`).
- `tools/run-local.sh` — 1280×720 window via `tools/preview.qml`; `tools/run-local.sh --fullscreen` runs `Jellyfin.qml` as the box would.
- `QT_QPA_PLATFORM=offscreen tools/run-local.sh` — headless run, useful to catch QML warnings.
- Lint: `qmllint Jellyfin.qml Components/*.qml Core/*.qml Views/*.qml`
- 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.
**Deploying to the Freebox** uses the Freebox SDK's QtCreator plugin:
- SDK setup: https://dev.freebox.fr/sdk/player.html (Windows: https://github.com/fbx/freebox-qtcreator-plugin/issues/8)
- Open `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 the repo root 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.
- `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`.
- `Core/Session.qml` — servers (`ListModel`), `currentServer`, `currentUser`. Network calls are **mocked** via `_simulate()`; each has a `TODO API` comment naming the Jellyfin endpoint. Async functions use `callback(error, result)` — keep that shape when wiring the real API. Views call `session.cancel()` on destruction.
- `Components/` — reusable widgets, exposed through `Components/qmldir` (every new component must be listed there). `Theme` (colors, spacing, fonts) and `Remote` (`isAccept`/`isBack` key mapping) are singletons; files inside `Components/` need `import "."` to see them.
- `Views/` — one screen per file, each rooted in `Page` (title/subtitle header + content area). Current flow: `ServerSelect` → `ServerAdd` → `UserSelect` → `Login` (password or Quick Connect) → `Home` (placeholder).
## 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.
- In bindings, guard `page.session`/`page.navigator` against null: they are injected after bindings are first evaluated.
- Don't disable (`enabled: false`) a focused control during loading — it loses focus and the remote stops responding; guard with a `busy` flag instead.