Zoom Meeting SDK - Développement Linux

Conseils d'expert pour construire des bots de réunion headless avec le Zoom Meeting SDK sur Linux. Ce SDK permet la participation aux réunions côté serveur, la capture de médias bruts, la transcription et l'automatisation des réunions alimentée par l'IA.

Comment construire un bot de réunion qui se joint automatiquement et enregistre

Utilisez cette compétence quand l'exigence est :

• le bot se joint visiblement à une vraie réunion Zoom
• le bot enregistre lui-même les médias bruts
• ou le bot déclenche un flux d'enregistrement cloud géré par Zoom après le join

Chaîne de compétences :

• primaire : meeting-sdk/linux
• ajouter zoom-rest-api pour la recherche OBF/ZAK, la planification ou les paramètres d'enregistrement cloud
• ajouter zoom-webhooks quand la récupération d'enregistrement cloud post-réunion est requise

Flux minimal d'enregistrement brut :

JoinParam join_param;
join_param.userType = SDK_UT_WITHOUT_LOGIN;
auto& params = join_param.param.withoutloginuserJoin;
params.meetingNumber = meeting_number;
params.userName = "Recording Bot";
params.psw = meeting_password.c_str();
params.app_privilege_token = obf_token.c_str();

SDKError join_err = meeting_service->Join(join_param);
if (join_err != SDKERR_SUCCESS) {
    throw std::runtime_error("join_failed");
}

// In MEETING_STATUS_INMEETING callback:
auto* record_ctrl = meeting_service->GetMeetingRecordingController();
if (!record_ctrl) {
    throw std::runtime_error("recording_controller_unavailable");
}

if (record_ctrl->CanStartRawRecording() != SDKERR_SUCCESS) {
    throw std::runtime_error("raw_recording_not_permitted");
}

SDKError record_err = record_ctrl->StartRawRecording();
if (record_err != SDKERR_SUCCESS) {
    throw std::runtime_error("start_raw_recording_failed");
}

GetAudioRawdataHelper()->subscribe(new MyAudioDelegate());

Utilisez l'enregistrement brut quand le bot doit posséder les médias PCM/YUV ou alimenter directement un pipeline IA. Utilisez l'enregistrement cloud + webhooks quand l'exigence est des actifs MP4/M4A/transcript gérés par Zoom après la réunion.

Documentation officielle : https://developers.zoom.us/docs/meeting-sdk/linux/ Référence API : https://marketplacefront.zoom.us/sdk/meeting/linux/ Exemple de dépôt (Enregistrement brut) : https://github.com/zoom/meetingsdk-linux-raw-recording-sample Exemple de dépôt (Headless) : https://github.com/zoom/meetingsdk-headless-linux-sample

Liens rapides

Nouveau sur Meeting SDK Linux ? Suivez ce chemin :

1. linux.md - Guide de démarrage rapide avec flux complet
2. concepts/high-level-scenarios.md - Architectures de bot production
3. meeting-sdk-bot.md - Bot résilient avec logique de réessai
4. references/linux-reference.md - Dépendances, Docker, CMake

Cas d'usage courants :

• Bot de Transcription → high-level-scenarios.md#scenario-1-transcription-bot
• Bot d'Enregistrement → high-level-scenarios.md#scenario-2-recording-bot
• Assistant IA de Réunion → high-level-scenarios.md#scenario-3-ai-meeting-assistant
• Surveillance de la Qualité → high-level-scenarios.md#scenario-4-monitoring-quality-bot
• Bot Auto-Join + Enregistrement → meeting-sdk-bot.md pour l'orchestration d'enregistrement brut, réessai et transfert d'enregistrement cloud

Vous rencontrez des problèmes ?

• Problèmes audio Docker → references/linux-reference.md#pulseaudio-setup
• Permission d'enregistrement brut refusée → meeting-sdk-bot.md#raw-recording-permission-denied
• Erreurs de build → references/linux-reference.md#troubleshooting

Règle de routage pour les bots

Si l'utilisateur demande de construire un bot qui se joint automatiquement à une réunion Zoom et l'enregistre, commencez par meeting-sdk-bot.md.

• Utilisez Meeting SDK Linux pour le participant visible, le flux de join et le contrôle d'enregistrement brut.
• Chaînez zoom-rest-api quand le bot doit récupérer les tokens OBF/ZAK, planifier des réunions ou activer les paramètres d'enregistrement côté compte.
• Chaînez zoom-webhooks quand l'exigence est la récupération d'enregistrement cloud Zoom après la fin de la réunion.

Aperçu du SDK

Le Zoom Meeting SDK pour Linux est une bibliothèque C++ optimisée pour les environnements serveur headless :

• Opération Headless : Aucune GUI requise, parfait pour Docker/cloud
• Accès aux données brutes : Vidéo YUV420, audio PCM à 32 kHz
• GLib Event Loop : Gestion asynchrone des événements pour les callbacks
• Docker-Ready : Dockerfiles préconfigurés pour CentOS/Ubuntu
• Intégration PulseAudio : Appareils audio virtuels pour les environnements headless

Différences clés avec le Video SDK

Prérequis

Configuration système

• OS : Ubuntu 22+, CentOS 8/9, Oracle Linux 8
• Architecture : x86_64
• Compilateur : gcc/g++ avec support C++11
• Outils de build : cmake 3.16+

Dépendances de développement

# Ubuntu
apt-get install -y build-essential cmake \
    libx11-xcb1 libxcb-xfixes0 libxcb-shape0 libxcb-shm0 \
    libxcb-randr0 libxcb-image0 libxcb-keysyms1 libxcb-xtest0 \
    libglib2.0-dev libcurl4-openssl-dev pulseaudio

# CentOS
yum install -y cmake gcc gcc-c++ \
    libxcb-devel xcb-util-image xcb-util-keysyms \
    glib2-devel libcurl-devel pulseaudio

Identifiants requis

1. App Zoom Meeting SDK (Client ID & Secret) → Créer sur Marketplace
2. JWT Token → Générer à partir du Client ID/Secret
3. Pour les réunions externes : Token OBF OU token ZAK → Obtenir via REST API
4. Pour l'enregistrement brut : Meeting Recording Token (optionnel) → Obtenir via API

Démarrage rapide

1. Télécharger et extraire le SDK

# Télécharger depuis https://marketplace.zoom.us/
tar xzf zoom-meeting-sdk-linux_x86_64-{version}.tar

# Organiser les fichiers
mkdir -p demo/include/h demo/lib/zoom_meeting_sdk
cp -r h/* demo/include/h/
cp lib*.so demo/lib/zoom_meeting_sdk/
cp -r qt_libs demo/lib/zoom_meeting_sdk/
cp translation.json demo/lib/zoom_meeting_sdk/json/

# Créer le symlink requis
cd demo/lib/zoom_meeting_sdk && ln -s libmeetingsdk.so libmeetingsdk.so.1

2. Initialiser et authentifier

#include "zoom_sdk.h"

USING_ZOOM_SDK_NAMESPACE

// Initialiser le SDK
InitParam init_params;
init_params.strWebDomain = "https://zoom.us";
init_params.enableLogByDefault = true;
init_params.rawdataOpts.audioRawDataMemoryMode = ZoomSDKRawDataMemoryModeHeap;
InitSDK(init_params);

// Authentifier avec JWT
AuthContext auth_ctx;
auth_ctx.jwt_token = your_jwt_token;
CreateAuthService(&auth_service);
auth_service->SDKAuth(auth_ctx);

3. Se joindre à la réunion

// In onAuthenticationReturn callback
void onAuthenticationReturn(AuthResult ret) {
    if (ret == AUTHRET_SUCCESS) {
        JoinParam join_param;
        join_param.userType = SDK_UT_WITHOUT_LOGIN;

        auto& params = join_param.param.withoutloginuserJoin;
        params.meetingNumber = 1234567890;
        params.userName = "Bot";
        params.psw = "password";
        params.isVideoOff = true;
        params.isAudioOff = false;

        meeting_service->Join(join_param);
    }
}

4. Accéder aux données brutes

// In onMeetingStatusChanged callback
void onMeetingStatusChanged(MeetingStatus status, int iResult) {
    if (status == MEETING_STATUS_INMEETING) {
        auto* record_ctrl = meeting_service->GetMeetingRecordingController();

        // Démarrer l'enregistrement brut (active l'accès aux données brutes)
        if (record_ctrl->CanStartRawRecording() == SDKERR_SUCCESS) {
            record_ctrl->StartRawRecording();

            // S'abonner à l'audio
            auto* audio_helper = GetAudioRawdataHelper();
            audio_helper->subscribe(new MyAudioDelegate());

            // S'abonner à la vidéo
            IZoomSDKRenderer* video_renderer;
            createRenderer(&video_renderer, new MyVideoDelegate());
            video_renderer->setRawDataResolution(ZoomSDKResolution_720P);
            video_renderer->subscribe(user_id, RAW_DATA_TYPE_VIDEO);
        }
    }
}

Fonctionnalités clés

Pièges critiques et bonnes pratiques

⚠️ CRITIQUE : PulseAudio pour Docker/Headless

Le problème #1 pour l'audio brut dans Docker :

L'audio brut nécessite PulseAudio et un fichier de configuration, même dans les environnements headless.

Solution :

# Installer PulseAudio
apt-get install -y pulseaudio pulseaudio-utils

# Créer le fichier de configuration
mkdir -p ~/.config
cat > ~/.config/zoomus.conf << EOF
[General]
system.audio.type=default
EOF

# Démarrer PulseAudio avec les appareils virtuels
pulseaudio --start --exit-idle-time=-1
pactl load-module module-null-sink sink_name=virtual_speaker
pactl load-module module-null-sink sink_name=virtual_mic

Voir : references/linux-reference.md#pulseaudio-setup

Permission d'enregistrement brut requise

Contrairement au Video SDK, le Meeting SDK nécessite une permission explicite pour accéder aux données brutes :

// DOIT appeler StartRawRecording() en premier
auto* record_ctrl = meeting_service->GetMeetingRecordingController();

SDKError can_record = record_ctrl->CanStartRawRecording();
if (can_record == SDKERR_SUCCESS) {
    record_ctrl->StartRawRecording();
    // MAINTENANT vous pouvez vous abonner à l'audio/vidéo
} else {
    // Nécessite : statut de host/co-host OU token d'enregistrement
}

Façons d'obtenir la permission :

1. Le bot est host/co-host
2. L'hôte accorde la permission d'enregistrement
3. Utiliser le paramètre recording_token (obtenir via REST API)
4. Utiliser app_privilege_token (OBF) lors du join

GLib Main Loop requise

Les callbacks du SDK s'exécutent via la boucle d'événements GLib :

#include <glib.h>

// Configurer la boucle principale
GMainLoop* loop = g_main_loop_new(NULL, FALSE);

// Ajouter un timeout pour les tâches périodiques
g_timeout_add_seconds(10, check_meeting_status, NULL);

// Exécuter la boucle (bloque jusqu'au quit)
g_main_loop_run(loop);

Sans la boucle GLib : Les callbacks ne se déclenchent jamais, le join reste en attente indéfiniment.

Mode mémoire Heap recommandé

Toujours utiliser le mode heap pour les données brutes pour éviter un débordement de pile avec les grandes images :

init_params.rawdataOpts.videoRawDataMemoryMode = ZoomSDKRawDataMemoryModeHeap;
init_params.rawdataOpts.shareRawDataMemoryMode = ZoomSDKRawDataMemoryModeHeap;
init_params.rawdataOpts.audioRawDataMemoryMode = ZoomSDKRawDataMemoryModeHeap;

Sécurité des threads

Les callbacks du SDK s'exécutent sur les threads du SDK :

• Ne pas effectuer d'opérations lourdes dans les callbacks
• Ne pas appeler CleanUPSDK() depuis les callbacks
• Utiliser des files d'attente thread-safe pour le passage de données
• Utiliser des mutex pour l'état partagé

Architectures production

Bot de transcription

Voir : concepts/high-level-scenarios.md#scenario-1

Se joindre à la réunion → Démarrer l'enregistrement brut → S'abonner à l'audio → 
Envoyer à AssemblyAI/Whisper → Générer une transcription en temps réel

Bot d'enregistrement

Voir : concepts/high-level-scenarios.md#scenario-2

Se joindre à la réunion → Démarrer l'enregistrement brut → S'abonner à l'audio+vidéo → 
Écrire YUV+PCM → Fusionner avec FFmpeg → Télécharger vers le stockage

Assistant IA de réunion

Voir : concepts/high-level-scenarios.md#scenario-3

Se joindre à la réunion → Transcription en temps réel → Analyse IA → 
Extraire les éléments d'action → Générer un résumé

Exemples d'applications

Dépôts officiels :

Ce que chacun démontre :

• Exemple d'enregistrement brut : Flux complet de données brutes, configuration PulseAudio, support multi-distribution Docker
• Exemple Headless : Intégration AssemblyAI, IA Anthropic, gestion de configuration prête pour la production

Bibliothèque de documentation

Concepts clés

• linux.md - Démarrage rapide et flux central
• concepts/high-level-scenarios.md - Architectures de bot production
• meeting-sdk-bot.md - Bot résilient avec logique de réessai

Référence plateforme

• references/linux-reference.md - Dépendances, CMake, Docker, dépannage

Authentification

• ../references/authorization.md - Génération JWT du SDK
• ../references/bot-authentication.md - Types de tokens bot (ZAK, OBF, JWT)

Fonctionnalités avancées

• ../references/breakout-rooms.md - Salles de groupes programmatiques
• ../references/ai-companion.md - Contrôles AI Companion

Problèmes courants

Dépannage complet : references/linux-reference.md#troubleshooting

Ressources

• Docs officiels : https://developers.zoom.us/docs/meeting-sdk/linux/
• Référence API : https://marketplacefront.zoom.us/sdk/meeting/linux/
• Forum des développeurs : https://devforum.zoom.us/
• Exemples GitHub :
  • https://github.com/zoom/meetingsdk-linux-raw-recording-sample
  • https://github.com/zoom/meetingsdk-headless-linux-sample

Besoin d'aide ? Commencez par linux.md pour le démarrage rapide, puis explorez high-level-scenarios.md pour les modèles production.

Opérations

• RUNBOOK.md - Liste de vérification de préflight et débogage de 5 minutes.