Control the Freebox player via Gladys.
Play, pause, fast-forward and rewind options… standby and wake-up, of course.
And why not retrieve a program guide that allows clicking on it to switch to the corresponding channel.
hi @b3n.0
are you talking about the Freebox Révolution (controllable with the Freebox
Hi @mutmut,
No, I’m really talking about the freeplayer, the second set-top box and, unless I’m mistaken, regardless of the version, these players all share the same API…
I was also talking about the player, and I can tell you they’re unfortunately very different (Free’s OS versus Android TV), because I moved from the Révolution to the Pop and lost access to the controls from third‑party apps.
Et oui… la fameuse freetelec ! Je l’ai utilisée longtemps, ils ont fermé la possibilité des appli tierces pour toutes les freebox (j’ai longtemps eu une révolution et maintenant la devialet) on passe par la l’application officielle qui a une télécommande…
Mais si je ne me trompe pas, c’était juste des envoi de commande via http sans réponse !
Ça ressemble à ça : http://hd1.freebox.fr/pub/remote_control?..
En fouillant, j’ai rassemblé ça, mais sans savoir l’utiliser :
{
« notes »: « Cheat-sheet pour Freebox Player via FreeboxOS (endpoints JSON). Remplace MAFREEBOX par l’IP/hostname local (ex: mafreebox.freebox.fr) et {id_player} par l’id renvoyé par /api/vX/player. Les versions d’API (vX / v6 / vN) peuvent varier selon box/firmware. »,
« auth »: {
« overview »: « Flow d’authentification FreeboxOS : register app → authorize (user confirme sur panneau) → GET /api/vX/login to obtain challenge → POST /api/vX/login/session with hmac(challenge, app_token) → use session_token in header X-Fbx-App-Auth for subsequent calls. »,
« endpoints »: [
{
« description »: « Get API version / discovery »,
« method »: « GET »,
« url »: « https://MAFREEBOX/api_version »,
« headers »: {},
« example_response »: {
« success »: true,
« result »: {
« api_version »: « v8 »,
« device_type »: « Freebox Server »
}
}
},
{
« description »: « Request authorization (register app) → returns track_id and pending status »,
« method »: « POST »,
« url »: « https://MAFREEBOX/api/vX/login/authorize/ »,
« headers »: {
« Content-Type »: « application/json »
},
« body_example »: {
« app_id »: « com.example.myapp »,
« app_name »: « My App »,
« app_version »: « 0.1 »,
« device_name »: « RaspberryPi »
},
« notes »: « User must validate the request on the Freebox front panel to receive an app_token. »
},
{
« description »: « Get challenge (needed to compute session password) »,
« method »: « GET »,
« url »: « https://MAFREEBOX/api/vX/login/ »,
« headers »: {},
« example_response »: {
« success »: true,
« result »: {
« logged_in »: false,
« challenge »: « RANDOM_CHALLENGE_STRING »
}
}
},
{
« description »: « Open session: POST password = hmac_sha1(app_token, challenge) »,
« method »: « POST »,
« url »: « https://MAFREEBOX/api/vX/login/session/ »,
« headers »: {
« Content-Type »: « application/json »
},
« body_example »: {
« app_id »: « com.example.myapp »,
« app_version »: « 0.1 »,
« password »: « HMAC_SHA1(app_token, challenge) »
},
« example_response »: {
« success »: true,
« result »: {
« session_token »: « SESSION_TOKEN_STRING »,
« rights »: [« settings »,« player »,« explorer »]
}
},
« note »: « Use the returned session_token as header X-Fbx-App-Auth for authenticated calls. »
}
],
« auth_header »: {
« name »: « X-Fbx-App-Auth »,
« value »: « SESSION_TOKEN_STRING »,
« usage »: « Include this header on all subsequent authenticated HTTP requests (and in WebSocket handshake). »
}
},
« discovery »: {
« list_players »: {
« method »: « GET »,
« url »: « https://MAFREEBOX/api/vX/player »,
« headers »: { « X-Fbx-App-Auth »: « SESSION_TOKEN » },
« example_response »: {
« success »: true,
« result »: [
{
« id »: 2,
« uid »: « player-XXXX »,
« model »: « Freebox Player Pop »,
« mac »: « AA:BB:CC:DD:EE:FF »,
« api_available »: true,
« api_version »: « v6 »,
« reachable »: true
}
]
},
« note »: « Use the id and api_version fields to build player-specific endpoints. »
}
},
« player_endpoints »: {
« base_pattern »: « /api/vX/player/{id_player}/api/{api_version}/ »,
« endpoints »: [
{
« name »: « Get player status »,
« method »: « GET »,
« url »: « https://MAFREEBOX/api/vX/player/{id_player}/api/{api_version}/status »,
« headers »: { « X-Fbx-App-Auth »: « SESSION_TOKEN » },
« example_response_success »: {
« success »: true,
« result »: {
« power »: « on »,
« current_app »: « tv »,
« volume »: { « mute »: false, « level »: 61 },
« current_media »: { « type »: « tv », « channel »: 2, « title »: « France 2 » }
}
},
« notes »: [
« May return limited info or error if the player model/firmware doesn’t support status API (common on some AndroidTV players). »,
« If you get invalid_api_version or missing fields, the model likely doesn’t expose that endpoint reliably. »
],
« sources »: [« dev.freebox.fr », « community reports »]
},
{
« name »: « Set volume / mute »,
« method »: « PUT »,
« url »: « https://MAFREEBOX/api/vX/player/{id_player}/api/{api_version}/control/volume/ »,
« headers »: { « X-Fbx-App-Auth »: « SESSION_TOKEN », « Content-Type »: « application/json » },
« body_examples »: [
{ « volume »: 61 },
{ « mute »: true },
{ « mute »: false }
],
« example_response_success »: {
« success »: true,
« result »: { « mute »: false, « volume »: 61 }
},
« notes »: [
« Works on models that expose volume control via Player API (reported OK on some Devialet/Delta and some older models). »,
« May return not_implemented / function not available on some models. »
],
« sources »: [« dev.freebox.fr », « bug reports »]
},
{
« name »: « Media control (play / pause / stop / next / prev) »,
« method »: « POST »,
« url »: « https://MAFREEBOX/api/vX/player/{id_player}/api/{api_version}/control/mediactrl »,
« headers »: { « X-Fbx-App-Auth »: « SESSION_TOKEN », « Content-Type »: « application/json » },
« body_examples »: [
{ « command »: « play » },
{ « command »: « pause » },
{ « command »: « stop » },
{ « command »: « next » },
{ « command »: « prev » }
],
« example_response_success »: {
« success »: true,
« result »: {}
},
« notes »: [
« Available on devices that provide media controls through the Player API. »,
« Some devices may return not_implemented. »
],
« sources »: [« dev.freebox.fr », « project tasks »]
},
{
« name »: « Open URL / Open TV channel / Launch app »,
« method »: « POST »,
« url »: « https://MAFREEBOX/api/vX/player/{id_player}/api/{api_version}/control/open »,
« headers »: { « X-Fbx-App-Auth »: « SESSION_TOKEN », « Content-Type »: « application/json » },
« body_examples »: [
{ « url »: « tv:?channel=2 » },
{ « url »: « app://com.freebox.someapp » },
{ « url »: « http://example.com/somepage » }
],
« example_response_error »: {
« success »: false,
« error_code »: « internal_error »,
« msg »: « Cannot open resource »
},
« notes »: [
« Common pattern to change channel: POST { "url": "tv:?channel=2" }. »,
« Many reports show open can fail with cannot parse json or internal errors depending on model/firmware — test carefully. »
],
« sources »: [« dev.freebox.fr bug FS#40136 », « community threads »]
},
{
« name »: « Remote / send key (navigation / OK / Back / etc.) »,
« method »: « POST »,
« url »: « https://MAFREEBOX/api/vX/player/{id_player}/api/{api_version}/control/remote »,
« headers »: { « X-Fbx-App-Auth »: « SESSION_TOKEN », « Content-Type »: « application/json » },
« body_examples »: [
{ « key »: « up » },
{ « key »: « down » },
{ « key »: « left » },
{ « key »: « right » },
{ « key »: « ok » },
{ « key »: « back » },
{ « key »: « home » }
],
« example_response_success »: {
« success »: true,
« result »: {}
},
« notes »: [
« Endpoint name may vary across firmwares (some implementations use input or remote_control). If POST /remote returns 403 or not implemented, try the UDP/HID remote SDK instead. »,
« Historically there was an http remote_control URL (deprecated/removed). »
],
« sources »: [« community examples », « historic docs »]
}
]
},
« websocket »: {
« note »: « You can open a WebSocket to the Freebox and must pass the same X-Fbx-App-Auth header in handshake. Useful to subscribe to player events instead of polling. »,
« reference »: « FreeboxOS WebSocket docs »
},
« compatibility_notes »: {
« summary »: « Behavior varies by player model & firmware. »,
« details »: [
« Older models (Révolution, Delta) tend to expose more Player endpoints reliably. »,
« AndroidTV-based players (Mini 4K, Pop) often have incomplete Player API support: status may return invalid_api_version or only minimal info. »,
« Some endpoints return error {"success":false, "error_code":"not_implemented"} — handle this gracefully in scripts. »,
« When in doubt: discover /api/vX/player to get api_version and test endpoints dynamically. »
],
« sources »: [
« dev.freebox.fr SDK / FreeboxOS docs »,
« Freebox bugtracker issues and community reports »
]
},
« example_curl_calls »: [
{
« desc »: « List players »,
« curl »: « curl -sS -H ‹ X-Fbx-App-Auth: SESSION_TOKEN › https://MAFREEBOX/api/vX/player »
},
{
« desc »: « Set volume to 40 »,
« curl »: « curl -sS -X PUT -H ‹ X-Fbx-App-Auth: SESSION_TOKEN › -H ‹ Content-Type: application/json › -d ‹ {"volume":40} › https://MAFREEBOX/api/vX/player/2/api/v6/control/volume/ »
},
{
« desc »: « Open TV channel 2 »,
« curl »: « curl -sS -X POST -H ‹ X-Fbx-App-Auth: SESSION_TOKEN › -H ‹ Content-Type: application/json › -d ‹ {"url":"tv:?channel=2"} › https://MAFREEBOX/api/vX/player/2/api/v6/control/open »
}
],
« final_advice »: « Start by obtaining a session token and calling GET /api/vX/player to discover available players and reported api_version. Then test status, volume and open endpoints in this order. Implement fallbacks when you get not_implemented / invalid_api_version errors. »
}