9.5 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, 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.- 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:
qmllint Jellyfin.qml Components/*.qml Core/*.qml Shared/*.qml Views/*.qml - 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 .thenQT_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.
FreeStore package: tools/package.py → dist/<identifier>.tar.gz (gitignored). Replicates the QtCreator plugin's "Make FreeStore Package": same file selection as Jellyfin.fbxproject (QML/JS/images/fonts/qmldir/manifest.json, excluding tools/ and hidden dirs), manifest checks (identifier \w+(\.\w+)+, 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: tools/deploy.py (Python stdlib only; Player must be in developer mode). It discovers the Player via SSDP (fbx:devel) or takes --box <IP>, serves the repo 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
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. The logo panel hides when the current page setsfullscreen: true(catalog and player screens).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.openItem(item)routes a catalog item toLibrary/Season/Details.Core/Session.qml— Jellyfin API client overXMLHttpRequest(_request(): JSON,Authorization: MediaBrowser …header withTokenonce signed in, per-request timeout via a dynamically createdTimersince Qt 5.5 XHR has none). Holds saved servers (ListModel, persisted throughfbx.applicationSettings— works on the box only; on the PCApp is not definedwarnings 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}/PlaybackInfoand/Sessions/Playing[/Progress|/Stopped]. API items are flattened by_toItem()(noindexkey: reserved role name inListModel). Image URLs viaposterUrl()/thumbUrl()/backdropUrl(). Async functions callcallback(error, result)witherrora 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 inPlaybackInfo: direct play H.264 only (the Revolution has no HEVC), otherwise HLS transcode. Text subtitles must stay declaredExternalandSubtitleStreamIndex: -1sent, or Jellyfin transcodes to burn them in (SubtitleCodecNotSupported).Components/— reusable widgets, listed inComponents/qmldir.MediaCard/MediaRowfor catalog cards and horizontal rows.VideoSurfacewraps the player: it tries the Freebox nativefbx.mediaVideoPlayerthen QtMultimediaVideo, both created withQt.createQmlObjectso a missing module doesn't break loading; it polls the backend and exposesposition/duration(ms) andplayerState. On the box,fbx.mediais 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/—Themesingleton (colors, spacing, fonts, card sizes; the only type inShared/qmldir),Remote.js(isAccept/isBackkey mapping) andFormat.js(durations, ticks↔ms, card labels), both.pragma library.Views/— one screen per file, each rooted inPage(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(PlayerViewis a plainFocusScope, not aPage).
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. - The box's virtual keyboard lacks
:(and likely/): never require typing a URL scheme orhost: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
tools/deploy.py(dev mode, app not installed), even with a Freebox profile open (profileId=1):Settingssaves fail withprofiles.application_data_set"internal json-rpc error", andQtQuick.LocalStorageexists 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.applicationApplicationdiffers from libfbxqml's: e.g. it hasprofileIdbut noidentifier. Don't rely on libfbxqml-only properties; guard withtypeof. - In bindings, guard
page.session/page.navigatoragainst 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
qmldirlisting 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 libraryJS files instead of new singletons; - no
import "."self-imports.
- every imported directory needs a
- Playback reporting must never clobber the server's resume point:
PlayerViewreports 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 abusyflag instead.