Project

General

Profile

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);

$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

Consulter les Schémas UML