Wiki : API de segmentation¶

Qu'est-ce que la segmentation ?¶

La segmentation consiste à détecter les locuteurs d'un fichier audio ou vidéo. Le fichier est ainsi divisé en segments correspondant aux prises de paroles des différents locuteurs.

Appel de l'API¶

Principes de l'API Voxilab¶

L'API Voxilab permet d'effectuer des opérations sur un serveur :

poster un fichier à segmenter ;
consulter le statut du fichier sur le serveur ;
récupérer des locuteurs et des segments.

Protocole de transport¶

Les requêtes vers le serveur sont faites grâce au protocole HTTP en mode REST.
Le retour est fait en Json.

URL d'appel et retour¶

En supposant que l'API est disponible sur le serveur voxilab.com.

Poster un fichier à segmenter¶

Requête HTTP de type POST.
URL : http://voxilab.com/files.json
Content-type : "multipart/form-data"
Corps : le fichier à segmenter
Réponse : Objet décrivant le fichier

{"id":5,"status":"uploaded"}

Avec id = identifiant du fichier sur le serveur ; status = état du fichier ("uploaded" s'il a été correctement transmis au serveur).

Consulter l'état du fichier sur le serveur¶

Requête HTTP
URL : http://voxilab.com/files.json/id_du_fichier
Réponse : Objet décrivant le fichier

{"id":5,"status":"diarization_phase7"}

Avec id = identifiant du fichier sur le serveur ; status = état du fichier.
Le fichier passe par 7 états successifs. L'état "diarization_phase7" signifie que la segmentation s'est correctement déroulée.

Consulter les locuteurs¶

Requête HTTP
URL : http://voxilab.com/files.json/id_du_fichier/speakers
Réponse : Tableau d'objets décrivant les locuteurs

[{"id":"S13","gender":"m","segments":[{"start":"4846.00","duration":"794.00","speaker":null},{"start":"3095.00","duration":"787.00","speaker":null}]},{"id":"S1","gender":"m","segments":[{"start":"5742.00","duration":"1097.00","speaker":null}]},...]

Avec id = identifiant du locuteur ; gender = sexe du locuteur ; segments = liste des segments du locuteur.

Consulter les segments¶

Requête HTTP
URL : http://voxilab.com/files.json/id_du_fichier/segments
Réponse : Tableau d'objets décrivant les segments

[{"start":"3.00","duration":"735.00","speaker":{"id":"S0","gender":"m"}},{"start":"848.00","duration":"1127.00","speaker":{"id":"S1","gender":"m"}},{"start":"1979.00","duration":"1099.00","speaker":{"id":"S13","gender":"m"}},...]

Avec start = temps de départ du segment ; duration = durée du segment ; speaker = locuteur du segment

Implémentation PHP de l'API¶

Les classes¶

voxilabDiarization : classe à appeler pour obtenir une instance de fichier segmenté.
voxilabSpeechfile : classe de fichier segmenté
voxilabSpeaker : classe qui décrit un locuteur
voxilabSegment : classe qui décrit un segment

Consulter les Schémas UML

Instanciation des classes¶

Il faut avant tout créer une instance de la classe voxilabDiarization :

$diarization = new voxilabDiarization($protocol, $options);

Où $protocol = protocole à utiliser ; $options = tableau d'options liées au protocole.
Le seul protocole actuellement implémenté est le protocole HTTP.
Les options sont donc relative à ce protocole :

$options = array(
        'url' => "http://voxilab.com/files.json",   // URL du serveur de segmentation
        'proxy' => "nom_du_proxy",                  // Nom du proxy HTTP
        'proxyuserpwd' => "[username]:[password]",  // Nom d'utilisateur et mot de passe pour la connexion avec le proxy
        'sslcert' => "nom_fichier_certificat.pem",  // Nom de fichier du certificat, au format PEM
        'sslkey' => "nom_fichier_cle_privee",       // Nom de fichier contenant la clé privée SSL
        'sslkeypasswd' => "mot_de_passe_ssl"        // Mot de passe secret utilisé par la clé SSL privée
        );

Si le fichier à traiter n'est pas encore sur le serveur, il faut l'envoyer grâce à la commande sendFile().

$speechFile = $diarization->sendFile(chemin_du_fichier);

S'il est déjà sur le serveur, il suffit de le récupérer grâce à son ID.

$speechFile = $diarization->getFile(id_du_fichier);

Ces commandes renvoient une instance du fichier segmenté.

Les méthodes de récupération d'informations s'appliquent maintenant sur l'instance $speechFile ainsi créée.

Récupération des informations¶

Obtenir les locuteurs¶

$speechFile->getSpeakers();

Réponse : Tableau d'objets voxilabSpeaker.

Obtenir les segments¶

$speechFile->getSegments();

Réponse : Tableau d'objets voxilabSegment.

Obtenir l'état du fichier¶

$speechFile->getStatus();

Réponse : Chaine de caractère.

Obtenir un locuteur par son ID¶

$speechFile->getSpeakerByID($id);

Paramètre : $id = Identifiant du locuteur.
Réponse : Objet voxilabSpeaker.

Obtenir un segment pour un temps donné¶

$speechFile->getSegmentByTime($temps);

Paramètre : $temps = Temps en centième de seconde.
Réponse : Objet voxilabSegment.

Obtenir les segments dans un intervalle de temps¶

$speechFile->getSegmentsInInterval($debut, $fin);

Paramètres : $debut = Temps de début de l'intervalle ; $fin = Temps de fin de l'intervalle.
Réponse : Tableau d'objets voxilabSegment.

Obtenir les segments d'un locuteur¶

$speechFile->getSegmentsBySpeaker($locuteur);

Paramètre : $locuteur = Identifiant du locuteur.
Réponse : Tableau d'objets voxilabSegment.

Schémas UML¶