Player API

Free n'ayant pas encore documenté l'API dédié au player, j'ai dû chercher un moment avant de trouver quelques informations.

Tout d'abord, il est à noter qu'il est nécessaire d'avoir les droits player sur Freebox OS pour l'application – ces droits ne pouvant se définir que manuellement :

À noter qu'il est bien sûr nécessaire de se loguer et d'envoyer l'en-tête X-Fbx-App-Auth dans tous les requêtes.

Lister les players

GET https://mafreebox.freebox.fr/api/v6/player

Réponse :

{
    "result": [
      {
          "api_available": true,
          "api_version": "7.0",
          "device_name": "Freebox Player",
          "id": 1,
          "reachable": true,
          "stb_type": "stb_v6",
          "uid": "9f20347c10fcd7751f3e6543d3aafb86"
      }
    ],
    "success": true
}

Les players vont être listés. On notera que stb_type est stb_v6 pour la Freebox Révolution, mais stb_v7 pour la Freebox Delta et la One.

Ici on aura donc :

PLAYER_ID = 1;
PLAYER_API_VERSION = 'v7';

État du Player

GET https://mafreebox.freebox.fr/api/v6/player/PLAYER_ID/api/PLAYER_API_VERSION/status/

Réponse quand le player est éteint :

{
    "result": {
        "power_state": "standby"
    },
    "success": true
}

Réponse quand le player est allumé :

{
    "result": {
        "foreground_app": {
            "context": {},
            "cur_url": "tv://?bouquetId=675&channel=7",
            "package": "fr.freebox.tv",
            "package_id": 28
        },
        "power_state": "running"
    },
    "success": true
}

Récupération des chaines avec leur uuid

GET https://mafreebox.freebox.fr/api/v6/tv/channels/

Retourne les centaines de chaines avec leur uuid :

{
  "success": true,
  "result": {
    "uuid-webtv-404": {
      "uuid": "uuid-webtv-404",
      "name": "TEVA",
      "available": true,
      "logo_url": "https://mafreebox.freebox.fr/api/v6/tv/img/channels/logos68x60/uuid-webtv-404.png",
      "has_service": true,
      "short_name": "TEVA",
      "has_abo": true
    },
    "uuid-webtv-1204": {
      "uuid": "uuid-webtv-1204",
      "name": "Syfy",
      "available": false,
      "logo_url": "https://mafreebox.freebox.fr/api/v6/tv/img/channels/logos68x60/uuid-webtv-1204.png",
      "has_service": false,
      "short_name": "Syfy",
      "has_abo": false
    }
  }
}

Zapper sur une chaine

Cette action allumera automatiquement le player s'il ne l'est pas déjà. L'uuid de la chaine est fourni par https://mafreebox.freebox.fr/api/v6/tv/channels/.

POST https://mafreebox.freebox.fr/api/v6/player/PLAYER_ID/api/PLAYER_API_VERSION/control/open
{ "url": "tv://?uuid=uuid-webtv-XXXX" }

Réponse :

{
    "success": true
}

Récupération du volume

GET https://mafreebox.freebox.fr/api/v6/player/PLAYER_ID/api/PLAYER_API_VERSION/control/volume

Réponse :

{
  "success":true,
  "result":{
    "target":"avr",
    "valid":true,
    "mute":false,
    "volume":64
   }
}

Définir le volume (PAS ENCORE DISPONIBLE ?!)

L'API ci-dessous a été trouvée dans un code Python, mais ne semble pas encore être implémentée… Peut-être dans une future version ?

PUT https://mafreebox.freebox.fr/api/v6/player/PLAYER_ID/api/PLAYER_API_VERSION/control/volume
{ "volume":50 }

Ou :

PUT https://mafreebox.freebox.fr/api/v6/player/PLAYER_ID/api/PLAYER_API_VERSION/control/volume
{ "mute":true }

Contrôle de la lecture (PAS ENCORE DISPONIBLE ?!)

L'API partielle ci-dessous a été trouvée dans un code Python, mais ne semble pas encore être implémentée… Peut-être dans une future version ?

POST https://mafreebox.freebox.fr/api/v6/player/PLAYER_ID/api/PLAYER_API_VERSION/control/mediactrl { "paramètres exactes":"unknown" }

Les commandes disponibles devraient être :

{
  "play",
  "pause",
  "play_pause",
  "stop",
  "next",
  "prev",
  "seek_forward",
  "seek_backward",
  "seek_to",
  "repeat_all",
  "repeat_one",
  "repeat_off",
  "repeat_toggle",
  "shuffle_on",
  "shuffle_off",
  "shuffle_toggle",
  "record",
  "record_stop",
  "select_audio_track",
  "select_srt_track",
  "select_stream",
}

Avec d'autres paramètres… :

{"seek_position": 0, "type": "seek_position"}

media_control_stream = {"quality": "", "source": ""}

media_control_stream_args = {"stream": media_control_stream, "type": "stream"}

{"track_id": 0, "type": "track_id"}

{"args": media_control_stream_args, "cmd": "pause"}

Changer les droits

À noter qu'il est possible de changer les droits d'une application en utilisant le mot de passe de Freebox OS – ainsi on pourrait donner les droits player à une application.

POST https://mafreebox.freebox.fr/api/v6/login/request_perms/
{
 "password": "fa0c29b41d6c7adf74090dde053c0d295859de66",
  "permissions": {
   "player": true
  }
}

Le password doit être formé de la façon suivante :

// javascript en utilisant https://gist.github.com/Seldaek/1730205 pour Crypto.sha1_hmac
var password = Crypto.sha1_hmac("BS>@45D7=.0&" + session_token + "%3]4vXy24", sha1(password_salt + user_password))

Concernant les paramètres :

• Avec https://mafreebox.freebox.fr/api/v6/login/session/ qui va permettre de récupérer session_token et password_salt.
• user_password étant le mot de passe de l'utilisateur pour se connecter à Freebox OS.
• "BS>@45D7=.0&" et "%3]4vXy24" sont des chaines statiques.