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

3.8 KiB
Raw Blame History

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 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:

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.