3.8 KiB
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 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 withLIBFBXQML=). tools/run-local.sh— 1280×720 window viatools/preview.qml;tools/run-local.sh --fullscreenrunsJellyfin.qmlas 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.fbxprojectin QtCreator with the Freebox plugin; the run target deploys to a Freebox Player on the LAN (configured inJellyfin.fbxproject.user, which is machine-specific). Jellyfin.fbxprojectpackages every QML/JS/image/font/qmldirfile under the repo root plusmanifest.json— new files are picked up automatically.
Architecture
Jellyfin.qml— rootApplication: logo panel (1/3) +Navigator(2/3), owns the singleSessioninstance.Core/Navigator.qml— screen stack on aLoader.push("Name")loadsViews/NameView.qml; alsoreplace,pop,reset. Every view getsnavigatorandsessioninjected, plus any props passed topush. Remote Back/Escape pops; at the root it propagates (exits app). After loading, focus goes to the view'sinitialFocus.Core/Session.qml— servers (ListModel),currentServer,currentUser. Network calls are mocked via_simulate(); each has aTODO APIcomment naming the Jellyfin endpoint. Async functions usecallback(error, result)— keep that shape when wiring the real API. Views callsession.cancel()on destruction.Components/— reusable widgets, exposed throughComponents/qmldir(every new component must be listed there).Theme(colors, spacing, fonts) andRemote(isAccept/isBackkey mapping) are singletons; files insideComponents/needimport "."to see them.Views/— one screen per file, each rooted inPage(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; nolet/const/arrow functions) and no QtQuick.Controls. - Input is a TV remote: navigation uses
KeyNavigation+ explicit focus. On aListView, setKeyNavigation.priority: KeyNavigation.AfterItemso the list handles arrows itself and only hands off at its ends. - In bindings, guard
page.session/page.navigatoragainst 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 abusyflag instead.