Scripting/fr



Le module de scripts est un greffon expérimental de l'interface utilisateur qui permet de contrôler Audacity depuis un script Perl externe. Les commandes sont envoyées à Audacity par un tube nommé. Tout langage de script supportant les tubes nommés peut être utilisé à la place de Perl. Les scripts externes constituent une des façons d'étendre les fonctionnalités d'Audacity.

Le support des scripts est actuellement considéré comme expérimental et surtout destiné aux développeurs. Vous pouvez l'essayer mais ne vous étonnez pas trop en cas de problème.

Comment commencer avec les scripts
Audacity 2.0 ne peut être utilisé avec des scripts qu'en compilant un module de greffon à part provenant du SVN (système de contrôle de versions), appelé mod-script-pipe. Il vous faudra également le langage Perl pour expérimenter les exemples. Il est possible que nous fournissions un mod-script-pipe déjà compilé, peu de temps après la sortie d'Audacity 2.0. Si vous désirez utiliser les scripts mais que vous ne voulez pas en passer par les étapes de compilation, vous devrez attendre qu'il sorte.

Ce document concerne les versions SVN d'Audacity et de mod-script-pipe, à partir de novembre 2009. Notre objectif est de garder ce document le plus à jour possible sur le wiki afin qu'il continue de s'appliquer aux dernières constructions (builds) d'Audacity du SVN.

Compilation
Assurez-vous de disposer de la dernière version d'Audacity dans le SVN HEAD compilée et opérationnelle. Le module de scripts, "mod-script-pipe", se trouve dans le SVN (dans lib-src), mais n'est pas compilé automatiquement.

Avec MSVC, cliquez-droit sur le projet mod-script-pipe et sélectionnez Build. Si tout fonctionne correctement, la DLL sera placée dans le répertoire "modules".

Avec GCC, allez dans le répertoire lib-src/mod-script-pipe et tapez "make". Cela compilera le module et copiera le fichier ".so" vers le répertoire des modules.

Bien que mod-script-pipe permette à un script de communiquer avec Audacity, il ne s'occupe pas de l'interprétation et du traitement effectif des commandes reçues. C'est Audacity qui s'en charge, ce qui implique d'utiliser une version récente du programme principal ainsi que du module de scripts pour disposer de toutes les possibilités offertes par les scripts.

Tests
Un script de test basique, "scripts/pipe-test.pl", est inclus dans le SVN. Il requiert naturellement Perl. Il contient beaucoup de tests et de sous-programmes d'envoi de commandes dans le tube.

Lancez d'abord Audacity, puis exécutez le script de test.

Si tout se passe bien, les commandes du script seront envoyées à Audacity, exécutées et les résultats renvoyés au script.

Vous pouvez expérimenter en changeant les commandes dans le script (voir ci-dessous).

Si le script s'arrête en attendant une réponse, cela signifie probablement qu'Audacity n'a pas chargé le module de scripts. Examinez le rapport de sortie pour vérifier si c'est le cas.

Si le module n'a pas été chargé, il se peut qu'il n'ait pas été placé dans le bon répertoire ou parce que la version du module ne correspond pas à celle d'Audacity. La manière la plus sûre d'éviter ce problème consiste à compiler Audacity et mod-script-pipe depuis le SVN, en même temps.

Commandes
Ce qui suit constitue une documentation des parties d'Audacity qui peuvent actuellement être contrôlées par des scripts. Attention : tout ceci est susceptible de changer jusqu'à maturation du système. Remarquez également que les commandes et les paramètres sont sensibles à la casse.

Les appels de commandes doivent prendre la forme suivante, terminée par un saut de ligne :

La commande est alors exécutée et chaque réponse est écrite dans le tube (pipe) de retour, sur des lignes distinctes. La fin des réponses est signalée par une ligne vide. Les commandes suivantes ne doivent pas être envoyées tant que toutes les réponses n'ont pas été lues.


 * Voir également les commandes additionnelles sur le wiki d'Audacity.

BatchCommands
Elle peut être appelée différemment depuis d'autres commandes car, actuellement, toutes les commandes non reconnues sont traitées comme des commandes batch (par lot). Pour comprendre ce que font ces commandes et comment elles doivent être formées, vous pouvez examiner le dialogue "Éditer les scripts". Par exemple, le système batch peut être utilisé pour appliquer un effet à un signal audio sélectionné.

Il est également possible d'appeler explicitement une commande batch mais vous devez savoir qu'une valeur de paramètre ne peut actuellement pas contenir d'espace, ce qui restreint passablement l'utilité de cette méthode. Si ChainName est fourni, la commande applique la chaîne batch sauvegardée sous ce nom au lieu d'une simple commande.

Paramètres:

Exemple:

CompareAudio
À partir de deux pistes sélectionnées, cette commande compare les pistes échantillon par échantillon et compte le nombre d'échantillons dont la différence absolue dépasse le seuil indiqué. Le nombre total d'échantillons est renvoyé, ainsi que le nombre de secondes de signal audio que ces échantillons représentent.

Paramètres:

Exemple:

MenuCommand
Exécute une 'commande de menu' en utilisant le système qui contrôle les menus d'Audacity. C'est simple mais puissant et beaucoup de tâches qui peuvent être effectuées dans les menus ou avec des raccourcis-clavier peuvent également être déclenchées par un script en utilisant cette commande. GetAllMenuCommands donne une liste complète de toutes les commandes disponibles.

Paramètres:

Exemples:

GetAllMenuCommands
Renvoie une liste de toutes les commandes de menu disponibles, qui peuvent être envoyées en utilisant MenuCommand.

Pas de paramètres.

-

GetTrackInfo
Renvoie au script des informations sur les pistes d'un projet.

Paramètres:

Exemples:

Help
Renvoie des informations sur les paramètres acceptés par une commande donnée.

Paramètres:

Exemple:

Message
Envoie un message au destinataire d'état de la commande. Comme les messages d'état de la commande sont actuellement renvoyés au script (si la commande a été déclenchée par un script), cela signifie que le message est renvoyé au script.

Paramètres:

Exemple:

Screenshot
Cette commande de copie d'écran (screenshot) est fortement inspirée du dialogue "Outils de capture d'écran" et prend trois paramètres.

paramètres:

Exemple:

Select
Permet de contrôler la zone de sélection du projet. Les pistes comprises inclusivement entre FirstTrack et LastTrack sont sélectionnées et l'intervalle sélectionné va de StartTime à EndTime. Si en revanche TrackName est spécifié, c'est cette piste qui est sélectionnée.

Paramètres:

Exemple:

GetPreference
Renvoie la valeur de la préférence demandée.

Parameters:

Exemple:

SetPreference
Modifie la valeur d'une préférence.

Paramètres:

Exemple:

SetTrackInfo
Change les informations des pistes, uniquement leur nom pour l'instant. (Remarquez que l'état muet/solo peut être changé avec des commandes de menu).

Paramètres:

Exemple:

Import
Charge des données audio d'un fichier dans une piste. Le type de fichier est déterminé à partir de son extension et tout format connu d'Audacity peut être utilisé.

Paramètres:

Exemple:

Export
Sauve les données audio du projet vers un fichier. Le type du fichier est déduit de son extension et tout format connu d'Audacity peut être utilisé.

Paramètres:

Exemple:

Ajout de commandes à Audacity (pour les développeurs)
Pour appeler une commande depuis un script, un objet CommandType lui correspondant doit être ajouté au CommandDirectory, qui est une classe singleton. Un CommandType s'occupe de créer des objets de commande spécifiques qui se charge du traitement.

Pour implémenter une nouvelle commande appelée Toto, le plus simple est de créer de nouvelles classes TotoCommandType et TotoCommand qui dérivent respectivement de CommandType et de CommandImplementation, puis de redéfinir/surcharger les méthodes virtuelles selon le besoin. On ajoute ensuite une instance de TotoCommandType au CommandDirectory.

À l'avenir, la nature répétitive d'une partie de ce code pourrait être réduite, en utilisant par exemple des macros (comme dans wxwidgets). Pour plus d'informations sur le fonctionnement du système de commande, consultez le code source, en particulier les fichiers du répertoire src/commands.

Problèmes connus et fonctionnalités manquantes

 * Les paramètres ne peuvent pas contenir d'espace pour l'instant.
 * Les scripts gérant plusieurs projets à la fois risquent de poser des problèmes.
 * Pour certaines commandes de menu, la fenêtre du projet doit avoir le focus pour que la commande réussisse.
 * Les scripts n'ont aucun contrôle sur le type et la verbosité des réponses qu'ils reçoivent (et il n'est pas évident d'obtenir des réponses de "sortie" de commandes comme GetTrackInfo)
 * Les commandes actuelles pourraient valider plus strictement les paramètres.
 * Il n'existe pas de manière correcte d'arrêter ou d'interrompre les commandes.
 * Il reste de nombreuses parties d'Audacity qui ne peuvent pas être contrôlées par un script car les commandes correspondantes n'ont pas encore été créées.
 * En raison d'un léger problème de gestion des modules, le module de scripts n'est pas arrêté quand Audacity se termine. Cela signifie que les tubes de scripts ne sont pas correctement supprimés.
 * L'utilisation des tubes peut (ou non) poser des problèmes de sécurité. Il vaut mieux éviter d'utiliser mod-script-pipe sur un système multi-utilisateurs.
 * L'interface côté script est encore d'assez bas niveau. Il est possible de générer des bibliothèque pour des langages de script à partir des descriptions internes des commandes.