41 lines
3.8 KiB
Markdown
41 lines
3.8 KiB
Markdown
# 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.
|