Carnet Wiki

API de conversion de fichiers

Version 6 — Octobre 2013 — severo

Pour réfléchir autour de l’idée d’une API et d’un système client/serveur pour la conversion de fichiers (documents, images, son, vidéos).

Objectifs

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

Un autre objectif est de mieux modulariser les plugins existants de conversion (doc2img, spipmotion, ocr, oficina, fulltext), 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. L’API se chargera uniquement du module de conversion.

Ce qu’on veut pouvoir faire

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

Actions de conversion possibles souhaitées avec l’API
Liste des actions souhaitées avec l’API
Fichier en entréeActionRésultatActuellement entréeActionRésultat
Documents doc , ou doc ou odt, rtf...

||
 |doc|convertir en odt|odt||
 |
 |doc|convertir en PDF|pdf|office2spip PDF|pdf |
|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 base64)|html |
|Documents PDF , ou PDF|ou tiff multipage, ps, epub ?||||
 ||
 |pdf|générer un vignette (image de la première page)|png|doc2img page)|png |
|pdf|générer une image par page|plusieurs png|doc2img png |
|pdf|extraire le texte brut (avec option OCR si aucun texte n’est inclus directement)|texte|fulltext , ocr directement)|texte |
|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 format|jpg |
|png|extraire le texte brut par OCR|texte|ocr OCR|texte |
|Sons||||
|mp3|encoder |||
 |mp3|convertir en un autre format|ogg|spipmotion format|ogg |
|mp3|extraire le texte correspondant (reconnaissance vocale, on peut rêver)|texte||
 |
 |Vidéos||||
|avi|encoder |||
 |avi|convertir en un autre format|ogv|spipmotion format|ogv |
|avi|extraire le texte correspondant (sous-titres automatiques reconnaissance vocale , on peut rêver)|texte || rêver) | texte |

Mécanisme client - serveur

Client et Serveur

Le principe est le suivant : le client envoie un fichier au serveur en lui indiquant quel type de conversion il souhaite, le serveur le convertit puis met à disposition du client le résultat de la conversion.

Détails du serveur 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
  • récupérer un fichier ( par upload , ou en téléchargeant depuis une URL )
     -* effectuer 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 Client

Le client doit savoir :

  • formuler forger sa demande commande (par exemple , action + liste de paramètres -> JSON)
    -* s’authentifier sur le serveur -* 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)

Première requête

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

Plus de détails

En réponse à sa demande de conversion, le client reçoit une URL spécifique (par exemple http://serveur/5e7d55972e014b436f68b89cc5962290). Un requête vers cette URL rendra la réponse suivante :

Pour chacune de ces actions, le client donne accès au fichier (par URL ou par transfert) au serveur. Le serveur effectue l’action. Finalement il met à disposition du client une URL pour récupérer le résultat, durant le temps nécessaire à son téléchargement. Après quelques heures (paramètre à définir), le résultat est effacé et l’URL retourne un code d’erreur.

En retour de sa demande de conversion, le client reçoit une URL contenant par exemple une clé unique. Durant le temps de la conversion, l’URL retourne un statut HTTP qui indique que la conversion n’est pas fini. Lorsque le résultat est prêt, l’URL retourne le résultat. Le client doit donc accéder régulièrement à l’URL pour savoir si la conversion est terminée ou non.

Une fois le L’URL peut donner accès au fichier converti à télécharger directement , le serveur peut proposer le résultat sous les formes suivantes  :

  • ou fichier converti de données (téléchargement direct par exemple JSON )
    -* JSON contenant qui indique l’URL où télécharger le ou les fichier(s ) converti(s ) + autres informations éventuelles sur la conversion
  • JSON contenant directement fichiers , ou éventuellement qui contient lui même le résultat de la conversion ( dans le cas d’un texte ou html ) + autres informations éventuelles sur la conversion .

Dans le cas où le serveur est aussi installé dans le même site, le client peut court-circuiter l’API et accéder directement aux commandes système.

Le serveur authentifie le client, et donne lui 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).

Il faut se poser la question de savoir si un seul plugin peut fournir l’API pour toutes les actions de conversion, ou s’il faut une API différente pour chaque type de fichier, en raison des paramètres différents (résolution pour les images, échantillonage ? pour le son, ...).

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

  • email : pour identifier l’utilisateur
  • key : pour vérifier les droits
  • url : où télécharger le fichier
  • format : ce que l’URL spécifique retournera
    • 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)

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 ?

Ce que l’API ne fera pas

Publier -* 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 ».-* le café

Comment le faire ?

Plugins en relation

Les plugins existants peuvent être reliés : doc2img, spipmotion, facd, ocr, oficina, mediaspip_core, fulltext

Retour à la version courante

Toutes les versions

Se connecter