Zoom Video SDK - Développement Linux

Conseils experts pour développer avec le Zoom Video SDK sur Linux. Créez des bots headless, des applications de capture/injection de médias bruts et des intégrations UI personnalisées avec Qt/GTK.

Documentation officielle : https://developers.zoom.us/docs/video-sdk/linux/ Référence API : https://marketplacefront.zoom.us/sdk/custom/linux/ Référentiel d'exemples : https://github.com/zoom/videosdk-linux-raw-recording-sample

Liens rapides

Nouveau sur Video SDK ? Suivez ce parcours :

1. Modèle d'architecture SDK - Modèle universel en 3 étapes pour TOUTE fonctionnalité
2. Modèle de connexion de session - Code complet et fonctionnel pour rejoindre une session
3. Données brutes vs Canvas - CRITIQUE : Linux n'a PAS d'API Canvas - données brutes UNIQUEMENT
4. Capture vidéo brute - Capturez et traitez les images YUV420

Référence :

• Hiérarchie des singletons - Carte de navigation SDK à 5 niveaux
• Référence API - Documentation API complète
• Intégration Qt/GTK - Modèles de framework UI
• Dépannage - Diagnostics rapides
• SKILL.md - Navigation complète de la documentation

Des problèmes ?

• Configuration PulseAudio → Guide PulseAudio
• Dépendances Qt → Dépendances Qt
• Erreurs de compilation → Guide des erreurs de compilation

Différences clés par rapport à Windows/macOS

Aperçu du SDK

Le Zoom Video SDK pour Linux est une bibliothèque C++ optimisée pour :

• Bots Headless : Support Docker/WSL, aucun affichage requis
• Accès aux données brutes : Capturez la vidéo YUV420, l'audio PCM
• Injection de données brutes : Caméra/micro virtuelle pour les médias personnalisés
• Partage d'écran : Capturez ou injectez les données de partage
• Enregistrement cloud : Enregistrez les sessions sur le cloud Zoom
• Streaming en direct : Streamez vers les endpoints RTMP
• Transcription en direct : Parole en texte en temps réel
• Intégration Qt/GTK : Support complet des frameworks UI

Prérequis

Configuration système requise

• OS : Ubuntu 20.04+, Debian 11+ ou compatible
• Architecture : x64 (recommandée), ARM64
• Compilateur : GCC 9+, Clang 10+
• CMake : 3.14 ou ultérieur
• Qt5 : Fourni avec le SDK (N'INSTALLEZ PAS le Qt5 système)

Dépendances

sudo apt update
sudo apt install -y build-essential gcc cmake libglib2.0-dev liblzma-dev \
    libxcb-image0 libxcb-keysyms1 libxcb-xfixes0 libxcb-xkb1 libxcb-shape0 \
    libxcb-shm0 libxcb-randr0 libxcb-xtest0 libgbm1 libxtst6 libgl1 libnss3 \
    libasound2 libpulse0

# Pour Linux headless
sudo apt install -y pulseaudio

# Configuration PulseAudio (CRITIQUE pour l'audio)
mkdir -p ~/.config
echo "[General]" > ~/.config/zoomus.conf
echo "system.audio.type=default" >> ~/.config/zoomus.conf

# Répertoire de journalisation
mkdir -p ~/.zoom/logs

Démarrage rapide

#include "zoom_video_sdk_api.h"
#include "zoom_video_sdk_interface.h"
#include "zoom_video_sdk_delegate_interface.h"

USING_ZOOM_VIDEO_SDK_NAMESPACE

// 1. Créez le SDK
IZoomVideoSDK* sdk = CreateZoomVideoSDKObj();

// 2. Initialisez
ZoomVideoSDKInitParams init_params;
init_params.domain = "https://zoom.us";
init_params.enableLog = true;
init_params.logFilePrefix = "bot";
init_params.videoRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;
init_params.shareRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;
init_params.audioRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;

sdk->initialize(init_params);

// 3. Ajoutez un délégué
sdk->addListener(myDelegate);

// 4. Rejoignez la session
ZoomVideoSDKSessionContext ctx;
ctx.sessionName = "my-session";
ctx.userName = "Linux Bot";
ctx.token = "jwt-token";
ctx.audioOption.connect = true;
ctx.audioOption.mute = false;
ctx.videoOption.localVideoOn = false;

// Pour headless : Haut-parleur audio virtuel
ctx.virtualAudioSpeaker = new VirtualSpeaker();

IZoomVideoSDKSession* session = sdk->joinSession(ctx);

Voir Modèle de connexion de session pour le code complet.

Fonctionnalités clés

Pièges critiques

⚠️ CRITIQUE #1 : Pas d'API Canvas sur Linux

Problème : Le SDK Linux n'a PAS d'API Canvas comme Windows/Mac.

Solution : Vous DEVEZ utiliser le pipe de données brutes et implémenter votre propre rendu.

Voir : Données brutes vs Canvas

⚠️ CRITIQUE #2 : PulseAudio requis pour l'audio

Problème : Le SDK nécessite PulseAudio pour les fonctions audio brutes.

Solution :

sudo apt install -y pulseaudio
mkdir -p ~/.config
echo "[General]" > ~/.config/zoomus.conf
echo "system.audio.type=default" >> ~/.config/zoomus.conf

Voir : Configuration PulseAudio

⚠️ CRITIQUE #3 : Dépendances Qt5

Problème : Le SDK nécessite les bibliothèques Qt5 (fournies, PAS le Qt5 système).

Solution :

# Copier depuis le package SDK
cp -r samples/qt_libs/Qt/lib/* lib/zoom_video_sdk/

# Créer les liens symboliques
cd lib/zoom_video_sdk
for lib in libQt5*.so.5; do ln -sf $lib ${lib%.5}; done

Voir : Dépendances Qt

⚠️ CRITIQUE #4 : Mode mémoire Heap

Utilisez toujours le mode heap pour les données brutes :

init_params.videoRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;
init_params.shareRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;
init_params.audioRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;

⚠️ CRITIQUE #5 : Audio virtuel pour Headless

Problème : Les environnements Docker/headless n'ont pas d'appareils audio.

Solution : Utilisez le haut-parleur et le micro audio virtuels.

session_context.virtualAudioSpeaker = new VirtualSpeaker();
session_context.virtualAudioMic = new VirtualMic();

Voir : Audio/Vidéo virtuelle

Référentiels d'exemples

Exemples officiels

Architecture d'exemple

Bot Headless (Docker):
┌──────────────────────────────────┐
│  Haut-parleur/Micro audio virtuel│
├──────────────────────────────────┤
│  Traitement des données brutes   │
│  - YUV420 → Fichier/Stream

Fusionné depuis video-sdk/linux/SKILL.md

Index de documentation complet Zoom Video SDK Linux

Parcours de démarrage rapide

Si vous débutez avec le SDK, suivez cet ordre :

1. Lisez le modèle d'architecture → concepts/sdk-architecture-pattern.md

   • Formule universelle : Singleton → Délégué → S'abonner
   • Une fois que vous comprenez cela, vous pouvez implémenter n'importe quelle fonctionnalité

2. Comprenez les spécificités Linux → concepts/raw-data-vs-canvas.md

   • CRITIQUE : Linux n'a PAS d'API Canvas - données brutes UNIQUEMENT

3. Implémentez la connexion de session → examples/session-join-pattern.md

   • Code JWT complet + code de connexion de session

4. Configurez l'environnement → troubleshooting/pulseaudio-setup.md

   • Configuration PulseAudio (requise pour l'audio)
   • troubleshooting/qt-dependencies.md
   • Configuration de la bibliothèque Qt5 (fournie avec le SDK)

5. Implémentez les fonctionnalités → Choisissez parmi les exemples ci-dessous

Structure de la documentation

video-sdk/linux/
├── SKILL.md                          # Aperçu principal des compétences
├── SKILL.md                          # Ce fichier - guide de navigation
├── linux.md                          # Résumé de la plateforme
│
├── concepts/                         # Modèles architecturaux de base
│   ├── sdk-architecture-pattern.md  # Formule universelle pour TOUTE fonctionnalité
│   ├── singleton-hierarchy.md       # Guide de navigation à 5 niveaux
│   └── raw-data-vs-canvas.md        # Spécifique Linux : données brutes UNIQUEMENT
│
├── examples/                         # Code complet et fonctionnel
│   ├── session-join-pattern.md      # Auth JWT + connexion de session
│   └── command-channel.md           # Canal de commande avec threading
│
├── troubleshooting/                  # Guides de résolution de problèmes
│   ├── pulseaudio-setup.md          # Configuration audio
│   ├── qt-dependencies.md           # Configuration de la bibliothèque Qt5
│   ├── build-errors.md              # Problèmes de compilation courants
│   └── common-issues.md             # Flux de diagnostic rapide
│
└── references/                       # Documentation de référence
    └── linux-reference.md           # Hiérarchie API, méthodes, codes d'erreur

Par cas d'utilisation

Je veux créer un bot headless

1. Modèle d'architecture SDK - Comprendre le modèle
2. Modèle de connexion de session - Rejoindre les sessions
3. Configuration PulseAudio - Configurer l'audio
4. Données brutes vs Canvas - Comprendre les différences Linux

J'obtiens des erreurs de compilation

1. Guide des erreurs de compilation - Problèmes de compilation SDK
2. Dépendances Qt - Configuration Qt5
3. Problèmes courants - Diagnostics rapides

J'obtiens des erreurs d'exécution

1. Configuration PulseAudio - L'audio ne fonctionne pas
2. Dépendances Qt - Bibliothèque introuvable
3. Problèmes courants - Tables de codes d'erreur

Je veux utiliser le canal de commande

1. Canal de commande - Envoyer/recevoir des commandes
2. Problèmes courants - Exigences de threading

Je veux implémenter une fonctionnalité spécifique

1. Modèle d'architecture SDK - COMMENCEZ ICI !
2. Hiérarchie des singletons - Accédez à la fonctionnalité
3. Référence API - Signatures de méthodes

Documents les plus critiques

1. Modèle d'architecture SDK (DOCUMENT MAÎTRE)

concepts/sdk-architecture-pattern.md

Le modèle universel en 3 étapes :

1. Obtenez le singleton (SDK, assistants, session, utilisateurs)
2. Implémentez le délégué (rappels d'événements)
3. S'abonner et utiliser

2. Données brutes vs Canvas (SPÉCIFIQUE LINUX)

concepts/raw-data-vs-canvas.md

CRITIQUE : Contrairement à Windows/Mac, le SDK Linux n'a PAS d'API Canvas. Vous DEVEZ utiliser le pipe de données brutes.

3. Configuration PulseAudio (PROBLÈME LE PLUS COURANT)

troubleshooting/pulseaudio-setup.md

L'audio nécessite une configuration PulseAudio.

4. Dépendances Qt

troubleshooting/qt-dependencies.md

Le SDK nécessite les bibliothèques Qt5 fournies, PAS le Qt5 système.

Apprentissages clés

Découvertes critiques :

1. Linux n'a PAS d'API Canvas

   • Windows/Mac ont l'API Canvas pour la vidéo rendue par le SDK
   • Linux DOIT utiliser le pipe de données brutes
   • Voir : Données brutes vs Canvas

2. PulseAudio est OBLIGATOIRE

   • Le SDK nécessite PulseAudio pour l'audio brut
   • Doit configurer ~/.config/zoomus.conf
   • Voir : Configuration PulseAudio

3. Utilisez Qt5 fourni, PAS le Qt5 système

   • Le SDK inclut des versions Qt5 spécifiques
   • Copier depuis samples/qt_libs/
   • Voir : Dépendances Qt

4. Les assistants contrôlent uniquement VOS flux

   • videoHelper->startVideo() démarre VOTRE caméra
   • Pour voir les autres, abonnez-vous à leur VideoPipe
   • Voir : Hiérarchie des singletons

5. Appareils virtuels pour Headless

   • Docker/headless a besoin d'un haut-parleur/micro audio virtuel
   • Définir avant de rejoindre la session
   • Voir : Modèle de connexion de session

6. Toujours utiliser le mode mémoire Heap

   init_params.videoRawDataMemoryMode = ZoomVideoSDKRawDataMemoryModeHeap;

7. Boucle principale GLib requise

   • Les boucles while/sleep ne distribuent pas les événements SDK
   • Doit utiliser g_main_loop_run()
   • Voir : Problèmes courants

8. Tous les appels SDK doivent être sur le thread principal

   • Les appels SDK de thread d'arrière-plan retournent l'erreur 2 (Internal_Error)
   • Utilisez g_idle_add() pour programmer sur le thread principal GLib
   • Voir : Canal de commande

9. Le canal de commande est dans l'étendue de la session

   • Ne s'étend PAS sur différentes sessions
   • L'expéditeur et le destinataire doivent être dans la même session
   • Voir : Canal de commande

Référentiels d'exemples

• raw-recording-sample - Exemple de données brutes officiel
• qt-quickstart - Intégration UI Qt6
• gtk-quickstart - Intégration UI GTK3

Référence rapide

« Mon code ne se compile pas »

→ Guide des erreurs de compilation

« L'audio ne fonctionne pas »

→ Configuration PulseAudio

« Bibliothèque introuvable »

→ Dépendances Qt

« Comment implémenter [fonctionnalité] ? »

→ Modèle d'architecture SDK

« Que signifie ce code d'erreur ? »

→ Problèmes courants

Version du document

Basé sur Zoom Video SDK pour Linux v2.x

Bon codage !

N'oubliez pas : Le Modèle d'architecture SDK est votre clé pour déverrouiller l'intégralité du SDK. Lisez-le d'abord !

Opérations

• RUNBOOK.md - Liste de contrôle de décollage et de débogage en 5 minutes.