API de conversion de fichiers

Objectifs

On veut pouvoir permettre à un site hébergé sur un serveur ne proposant pas les outils système (binaires type ffmpeg, openoffice, tesseract...) de conversion, de pouvoir déléguer ce travail à un autre site.

Un autre objectif est de mieux modulariser les plugins existants de conversion, de récupération de métadonnées ou de contenu textuel, en séparant ce qui relève de la conversion, de l’indexation, du stockage et de la publication (affichage et téléchargement) des documents :

-* doc2img ;

• spipmotion ;
• ocr ;
• oficina ;
• fulltext ;

L’API se chargera uniquement du module de conversion.

Ce qu’on veut pouvoir faire

En partant d’un document original, on peut vouloir réaliser 3 actions différentes :

-* Convertir ce document dans un autre format afin de disposer d’une version « affichable » sur Internet ;

• Récupérer une vignette de ce document le représentant ;
• Récupérer des données textuelles issues du document dans le but de son indexation ;

Je liste ici toutes les actions de conversion qu’effectuent les plugins actuels + celles qu’on peut imaginer.

||Actions de conversion possibles||
|Fichier en entrée|Action|Résultat|Actuellement|
|Documents doc, ou odt, rtf...||||
|doc|convertir en odt|odt||
|doc|convertir en PDF|pdf|office2spip|
|doc|générer un vignette (image de la première page)|png||
|doc|générer une image par page|plusieurs png||
|doc|extraire le texte brut|texte||
|doc|convertir en HTML (avec option pour intégrer les images en base64)|html|oficina|
|Documents PDF, ou tiff multipage, ps, epub ?||||
|pdf|générer un vignette (image de la première page)|png|doc2img|
|pdf|générer une image par page|plusieurs png|doc2img|
|pdf|extraire le texte brut (avec option OCR si aucun texte n’est inclus directement)|texte|fulltext, ocr|
|pdf|convertir en HTML (avec option pour intégrer les images en base64)|html||
|pdf|convertir en doc (éventuellement)|doc||
|Images||||
|png|convertir en un autre format|jpg|doc2img|
|png|extraire le texte brut par OCR|texte|ocr|
|Sons||||
|tout format sonore|encoder en un autre format, ou une série d’autres formats lisibles sur Internet (HTML5)|ogg,mp3,aac|spipmotion|
|tout format sonore|récupération des métadonnées pour indexation (ID3, lyrics, durée...)|texte (en bdd ou fichier texte)|spipmotion,GetID3|
|tout format sonore|récupération d’une vignette de document issue des métadonnées (ID3...)|image (jpg,png)|spipmotion, GetID3|
|mp3|extraire le texte correspondant (reconnaissance vocale, on peut rêver)|texte||
|Vidéos||||
|tout format vidéo|encoder en un autre format, ou une série d’autres formats lisibles sur Internet (HTML5)|ogv,webm,mp4|spipmotion|
|tout format vidéo|récupération des métadonnées pour indexation (durée, taille...)|texte (en bdd ou fichier texte)|spipmotion, GetID3|
|tout format vidéo|récupération d’une vignette de document|image (jpg,png)|spipmotion|
|avi|extraire le texte correspondant (sous-titres automatiques, on peut rêver)|texte||

[note Fil : si on installe les bons binaires, on peut avoir en entrée et en sortie beaucoup plus de formats. Je pense notamment à pandoc ]

Mécanisme de communication client - serveur (API)

Le principe est le suivant :

1. le client envoie un fichier au serveur en lui indiquant quel type de conversion il souhaite ;
2. le serveur récupère le fichier ;
3. le serveur intègre dans une file d’attente de conversion cette demande (FACD par exemple qui est fait pour cela) ;
4. le serveur convertit ou extrait les informations demandées du fichier (en utilisant un des plugins cité plus haut) ;
5. le serveur met à disposition du client le résultat de la conversion ;
6. le client se charge de récupérer le résultat et de son intégration ;

Le client demande à intervalle régulier au serveur si la conversion est terminée ou non. Le serveur lui indique si la conversion est en attente, en cours ou terminée.

Détails du serveur

Le serveur doit savoir :

• décoder la commande du client (par exemple, JSON -> action + liste de paramètres)
• authentifier le client et autoriser ou non l’action demandée
• générer une URL spécifique au client (pour qu’il teste l’avancement de l’action de conversion, et qu’il récupère le résultat)
• récupérer un fichier (par upload direct, ou en téléchargeant depuis une URL)
• effectuer l’action de conversion
• mettre le résultat selon la forme demandée par le client (téléchargement direct, ou encapsulation résultat -> JSON)
• garder le résultat à disposition durant X temps (paramétrage du serveur), puis l’effacer

Détails du client

Le client doit savoir :

• formuler sa demande (par exemple, action + liste de paramètres -> JSON)
• envoyer le fichier (par upload ou en fournissant une URL)
• récupérer son URL spécifique
• utiliser régulièrement l’URL spécifique pour connaître l’avancement de l’action de conversion
• récupérer le résultat lorsque l’action est terminée
• extraire le résultat (par exemple, JSON -> résultat)

API - Envoi du fichier et demande de conversion

La première requête du client vers le serveur peut contenir :

• URL vers le fichier à télécharger, ou dans le cas d’une requête POST (Content-Type multipart/form-data) le fichier en lui même,
• liste de paramètres pour la conversion
• données pour l’authentification (email, clé)

Réponses possibles du serveur :

• 201 : conversion intégrée à la file d’attente. Renvoie une URL spécifique (par exemple http://serveur/5e7d55972e014b436f68b89cc5962290)
• 403 : action interdite
• 404 : dans le cas d’une URL passée en paramètre, URL mal formée
• 406 : format non pris en compte

API - Avancement de la conversion

Une fois la conversion en cours, le client peut effectuer une requête vers l’URL spécifique. Le serveur peut répondre :

• 200 : résultat à télécharger (fichier ou autre forme, voir le paragraphe suivant)
• 204 : le fichier original est en cours de téléchargement, ou en cours de conversion
• 403 : accès interdit
• 404 : aucun fichier n’a pu être récupéré depuis l’URL fournie en paramètre

La réponse 200 peut être sous une des trois formes suivantes (voir http://zone.spip.org/trac/spip-zone/browser/_plugins_/oficina/action/oficina_api_v1.php#L24) :

• directe (téléchargement direct du fichier converti)
• JSON contenant l’URL où télécharger le ou les fichier(s) converti(s) + autres informations éventuelles sur la conversion
• JSON contenant directement le résultat de la conversion (dans le cas d’un texte ou html) + autres informations éventuelles sur la conversion
• page de test avec formulaire de paramétrage et résultat en dessous.

API - Commandes d’administration

Le plugin oficina propose une autre commande (http://zone.spip.org/trac/spip-zone/browser/_plugins_/oficina/action/oficina_api_v1.php#L67) pour permettre à un administrateur de créer une clé d’accès pour un tiers.

Si le client est authentifié comme un administrateur, et qu’il envoie le paramètre « for=toto », le serveur répondra :

• 200 : clé pour « toto » = 5e7d55972e014b436f68b89cc5962290"
• 403 : accès interdit

API - autres commandes ?

Le serveur authentifie le client, et lui donne accès à tout ou partie des actions. On peut éventuellement imaginer que le serveur publie la liste des actions dont il est capable (méta-données décrivant le contenu du service et les paramètres acceptés). Voir par exemple la commande GetCapabilities du service Web WMS : https://fr.wikipedia.org/wiki/Web_Map_Service.

Exemple du plugin oficina

Les paramètres envoyés au serveur peuvent être (voir plugin oficina) :

• email : pour identifier l’utilisateur
• key : pour vérifier les droits : si la clé correspond à l’email, alors l’utilisateur a le droit de convertir le fichier
• url : où le serveur peut télécharger le fichier
• format : pour le résultat de la conversion
  • json : résultat encapsulé en format JSON
  • dl : téléchargement direct du résultat
  • vide : une page de test avec un formulaire (contenant tous ces champs) et le résultat affiché en dessous
• filter : paramètre pour la conversion doc -> html (traitements spécifiques)
• images inline : paramètre pour la conversion doc -> html (inclure les images en base64 dans le code HTML)

Ce que l’API ne fera pas

Publier le fichier converti sur le serveur. Le résultat ne sera accessible que par le client. Éventuellement, s’il existe un autre plugin de publication à distance (genre CDN), on pourra les coupler pour que la conversion d’une vidéo, par exemple, retourne en résultat un code HTML d’embed, ou une URL oembed, la visualisation de la vidéo convertie se faisant pour les visiteurs sur le serveur « CDN ».

Comment faire ?

Il existe déjà plusieurs plugins de conversion, d’analyse, d’indexation, ou de gestion des travaux. Les plugins suivants peuvent être éventuellement modifiés pour utiliser l’API d’une manière ou d’une autre : doc2img, spipmotion, facd, ocr, oficina, mediaspip_core, fulltext

Dans le cas où le client et le serveur sont installés sur le même site, il faut prévoir un mécanisme pour éviter les requêtes HTTP [note Fil : est-ce indispensable ? Autant avoir un seul modèle…].

Est-ce qu’un seul plugin peut fournir l’API pour toutes les actions de conversion, ou faut-il une API différente pour chaque type de fichier, en raison des paramètres différents (résolution pour les images, taux compression pour le son et les vidéos, ...).

Est-ce qu’utiliser une boucle DATA a un sens pour récupérer les données sur le serveur ? Avec un critère clé ou url_specifique ?