Documentation

Guide utilisateur Popcorn Client

Introduction

Popcorn Client est l'application qui vous permet de rechercher des films et séries, de lancer des téléchargements et de regarder vos contenus en streaming. Elle se connecte à un serveur Popcorn (popcorn-server) et peut utiliser un compte cloud (popcorn-web) pour synchroniser votre configuration entre plusieurs appareils.

En bref : vous installez le client, vous le connectez à votre serveur (et optionnellement à votre compte cloud), puis vous parcourez, recherchez et regardez vos contenus.

Vidéo de démonstration

Installation

Selon votre usage, vous pouvez utiliser Popcorn Client de plusieurs façons :

  • Windows (Desktop) : téléchargez l'installateur depuis la page Téléchargements du site (fichier .msi ou .exe). Installez puis lancez l'application.
  • Android : téléchargez l'APK depuis la page Téléchargements, installez-le sur votre appareil puis ouvrez l'application.
  • Web : si votre serveur propose l'accès au client en ligne, ouvrez l'URL indiquée dans votre navigateur.

Un compte cloud (inscription sur le site Popcorn) et un code d'invitation peuvent être nécessaires selon la configuration de votre instance.

Installation sur CasaOS / ZimaOS

Sur ZimaOS, CasaOS ou tout NAS utilisant Docker, Popcorn peut être installé via l'App Store (CasaOS) ou en déployant le fichier compose fourni. Deux conteneurs sont utilisés : le client (interface web) et le serveur (backend API).

Installation

Installez l'application Popcorn depuis l'App Store CasaOS ou importez le fichier YAML du projet. Au démarrage, le client (frontend) et le serveur (backend) sont lancés : le client est en général accessible sur le port 4325, le backend sur le port 3000.

Ouvrez l'URL du client indiquée par CasaOS (ex. http://IP_DE_VOTRE_NAS:4325) dans votre navigateur.

Volumes : chemins et dossiers

Que ce soit via CasaOS ou Docker, le conteneur serveur monte des volumes (base de données, téléchargements, cache de transcodage). Il faut :

  • Modifier les chemins des volumes dans la configuration (CasaOS ou docker-compose / YAML) pour qu'ils correspondent à votre machine (ex. remplacer /media/Docker/AppData/popcorn par votre chemin).
  • Créer ces dossiers sur l'hôte avant le premier démarrage, sinon le conteneur peut ne pas démarrer correctement.

Avec une image récente du backend, le serveur peut tourner en root (RUN_AS_ROOT=1, défaut sur CasaOS) ou sous un utilisateur (PUID:PGID, optionnel). Créez les dossiers si besoin ; si vous utilisez PUID:PGID et avez des erreurs de droits, vous pouvez faire un chown sur l'hôte. Ne pas définir user: dans le compose. Exemple : mkdir -p /votre/chemin/popcorn/.data /votre/chemin/popcorn/downloads /votre/chemin/popcorn/transcode_cache

Variable PUBLIC_BACKEND_URL

Si vous accédez au client depuis un autre appareil (PC, Mac, téléphone), le client doit connaître l'URL du backend telle que vue par le navigateur. Sinon, les requêtes vers l'API échouent (erreur « Failed to fetch » ou CORS).

Dans les paramètres de l'app Popcorn sur CasaOS, définissez PUBLIC_BACKEND_URL avec l'URL du backend telle que vue par le navigateur :

  • Exemple : si vous ouvrez le client à http://192.168.1.10:4325, définissez PUBLIC_BACKEND_URL=http://192.168.1.10:3000 (même IP ou hostname, port 3000).
  • Redémarrez le conteneur client après avoir modifié cette variable.

Connexion au serveur impossible (CORS / Failed to fetch)

Si le client s'affiche mais que le navigateur indique « Connexion au serveur impossible » ou une erreur CORS :

  • Vérifiez que le backend est joignable : depuis l'appareil où vous ouvrez le client, ouvrez http://IP_DU_NAS:3000/api/client/health dans un nouvel onglet. Si la page ne charge pas, le problème est réseau ou pare-feu (ouvrez le port 3000).
  • Définissez PUBLIC_BACKEND_URL comme indiqué ci-dessus, redémarrez le conteneur client puis rechargez la page.

Une erreur affichée comme CORS peut en réalité venir du fait que le backend n'est pas joignable depuis votre appareil (connexion refusée, timeout). Vérifier d'abord que l'URL du backend répond bien dans le navigateur.

Lecture vidéo impossible (Permission denied sur le cache HLS)

Si le serveur démarre mais que la lecture d'une vidéo échoue (chargement infini) et que les logs du conteneur server affichent « Impossible de créer le répertoire de sortie ... transcode_cache/hls » ou « Permission denied (os error 13) », le volume du cache de transcodage n'est pas accessible en écriture par le conteneur (lancez en root avec RUN_AS_ROOT=1, ou assurez-vous que le volume est accessible en écriture par l'utilisateur PUID:PGID si vous utilisez ce mode).

  • Repérez le chemin hôte monté sur transcode_cache dans votre configuration (ex. dans casaos.yaml : source: /media/Media/Popcorn/streaming).
  • Sur le NAS (SSH ou terminal) : sudo mkdir -p /media/Media/Popcorn/streaming puis sudo chown -R 1000:1000 /media/Media/Popcorn/streaming (adapter le chemin et remplacer 1000:1000 par votre PUID:PGID si besoin).
  • Redémarrez le conteneur server puis réessayez la lecture vidéo.

Première configuration

Au premier lancement, un assistant vous guide :

  1. Connexion au serveur : saisissez l'URL de votre serveur Popcorn (ex. http://192.168.1.10:3000). Si vous utilisez Quick Connect, scannez le QR code ou entrez le code fourni sur le site.
  2. Compte cloud (optionnel) : connectez-vous ou créez un compte pour synchroniser votre configuration.
  3. Indexers et TMDb : configurez votre clé API TMDb et activez les définitions d'indexers dont vous avez besoin (voir section Indexers).

Vous pouvez rouvrir l'assistant à tout moment via Paramètres > Configuration initiale.

Paramètres

Dans Paramètres, les options sont regroupées par catégories :

  • Système : configuration initiale, serveur, client torrent (librqbit), diagnostics.
  • Interface : préférences d'affichage, langue, thème.
  • Contenu : indexers (instances sur le serveur), synchronisation des torrents.
  • Découverte : sliders de la page d'accueil, gestion des demandes, liste noire.
  • Compte : compte utilisateur, feedback, amis, utilisateurs locaux.

Indexers et définitions d'indexers

Les indexers sont les sources qui permettent de rechercher des torrents (ex. Jackett, YGG). Ils sont configurés côté serveur (Paramètres > Indexers dans le client envoie la config au serveur).

Les définitions d'indexers sont le catalogue des indexers disponibles (pays, langue, etc.). Ce catalogue est fourni par le site Popcorn et vous choisissez dans le client quelles définitions activer (Paramètres > Définitions d'indexers).

En bref :

  • Sur le serveur, vous ajoutez et configurez des indexers (URL, clé API, etc.).
  • Dans le client, vous activez les définitions qui correspondent à ces indexers (même type / même ID).
  • Sans indexer correctement configuré côté serveur, la recherche ne renverra aucun résultat, même si les définitions sont activées dans le client.

Compte cloud

Un compte cloud (inscription sur le site Popcorn) permet de synchroniser votre configuration (indexers, préférences) entre plusieurs appareils et d'accéder à des fonctionnalités comme les invitations, les amis ou le feedback.

Connexion : utilisez les mêmes identifiants que sur le site. Si vous n'avez pas de compte, créez-en un depuis le site puis connectez-vous dans le client (Paramètres > Mon Compte ou lors de la configuration initiale).

Résolution de problèmes

Le serveur est inaccessible

  • Vérifiez l'URL du serveur (Paramètres > Configuration du Serveur).
  • Assurez-vous que le serveur Popcorn est démarré et joignable (pare-feu, réseau local ou VPN).

Le backend crash (Impossible de créer la base de données)

  • Cause la plus probable : le dossier monté (ex. /media/.../popcorn) appartient à root et n'est pas accessible en écriture par le conteneur.
  • Si vous n'utilisez pas RUN_AS_ROOT, corriger les droits pour que l'utilisateur du conteneur puisse écrire : sudo chown -R PUID:PGID /chemin/vers/popcorn puis sudo chmod -R 775 /chemin/vers/popcorn (ex. 1000:1000 pour PUID:PGID ; ou définir RUN_AS_ROOT=1 pour lancer en root).
  • Redémarrez le conteneur serveur et retestez http://IP_DU_NAS:3000/api/client/health.

J'ai ajouté un indexer mais je n'ai aucun résultat / aucun torrent synchronisé

  • Vérifiez que l'indexer est bien configuré et testé côté serveur (Paramètres > Indexers).
  • Vérifiez que des définitions d'indexers sont activées dans le client (Paramètres > Définitions d'indexers) et qu'elles correspondent aux indexers présents sur le serveur (même type ou ID).
  • Rafraîchissez ou resynchronisez les définitions si besoin.
  • Côté serveur : assurez-vous que les indexers (ex. Jackett) renvoient bien des résultats pour une recherche test.

Le téléchargement ne démarre pas

  • Vérifiez que le client torrent (qBittorrent, rqbit, etc.) est configuré et connecté côté serveur (Paramètres > Client torrent / librqbit).
  • Vérifiez les logs du serveur et du client torrent pour des erreurs (chemin de téléchargement invalide, port fermé, client arrêté).
  • Assurez-vous que le lien ou magnet est valide et que les trackers ou le DHT sont accessibles (pare-feu, VPN si besoin).

Erreurs de connexion au cloud (CORS, etc.)

  • En mode navigateur web, l'accès direct au site cloud peut être bloqué par CORS ; utilisez l'application desktop ou Android si le problème persiste.
  • Vérifiez que l'URL du site Popcorn (popcorn-web) est correcte dans la configuration si vous utilisez une instance personnalisée.

Où trouver les logs et diagnostics

  • Client : Paramètres > Diagnostics — vérification rapide des routes backend et de la connectivité.
  • Serveur : consultez les fichiers de logs ou l'interface d'administration du serveur Popcorn selon votre installation.