Scripting/fr
From Audacity Manual
|
|
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.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 :
| Commande: Param1=Valeur1 Param2=Valeur2 |
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:
| ChainName: | S'il est présent, applique la chaîne batch de ce nom |
| CommandName: | Nom de la commande batch à exécuter |
| ParamString: | Paramètres de la commande batch |
Exemple:
| Send | Receive |
| BatchCommand: CommandName=Noise | BatchCommand finished: OK |
| ChangeTempo: Percentage=10.0 | BatchCommand finished: OK |
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:
| Threshold: | Nombre en virgule flottante de 0.0 à 1.0 |
Exemple:
| Send | Receive |
| CompareAudio: Threshold=0.1 | Comparing tracks 'Audio Track 1' and 'Audio Track 2'. Finished comparison: 764480 samples (17.335 seconds) exceeded the error threshold of 0.200000. CompareAudio finished: OK |
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:
| CommandName: | Nom de la commande de menu à exécuter |
Exemples:
| Send | Receive |
| MenuCommand: CommandName=SplitDelete | MenuCommand finished: OK |
| MenuCommand: CommandName=Play | MenuCommand finished: OK |
| MenuCommand: CommandName=TrackMute | MenuCommand finished: OK |
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:
| TrackIndex: | Un entier (0 par défaut) identifiant la piste |
| Type: | Information à obtenir : Une valeur parmi : Name, StartTime, EndTime (défaut: Name) |
Exemples:
| Send | Receive |
| GetTrackInfo: Type=Name TrackIndex=0 | Audio Track GetTrackInfo finished: OK |
| GetTrackInfo: Type=EndTime TrackIndex=0 | 24.000000 GetTrackInfo finished: OK |
Help
Renvoie des informations sur les paramètres acceptés par une commande donnée.
Paramètres:
| CommandName: | La commande pour laquelle on veut de l'aide |
Exemple:
| Send | Receive |
| Help: CommandName=Select | Select Parameters: EndTime: a floating-point number (default: 0) FirstTrack: an integer (default: 0) LastTrack: an integer (default: 0) Mode: one of: None, All, Range, Name (default: All) StartTime: a floating-point number (default: 0) TrackName: any value (default: 0) Help finished: OK |
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:
| MessageString: | Le message à envoyer |
Exemple:
| Send | Receive |
| Message: MessageString=hello | hello Message finished: OK |
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:
| FilePath: | Une chaîne représentant le chemin du répertoire dans lequel les images doivent être sauvegardées. |
| CaptureMode: | Une chaîne spécifiant les zones de l'écran à capturer (fenêtre, fenêtre entière, fenêtre augmentée, plein écran, barre d'outils, barre se sélection, outils, contrôle, mixage, VU-mètre, édition, périhpérique, transcription, panneau des pistes, règle, pistes, première piste, deuxième piste).
Valeurs possibles : window, fullwindow, windowplus, fullscreen, toolbars, selectionbar, tools, control, mixer, meter, edit, device, transcription, trackpanel, ruler, tracks, firsttrack, secondtrack. |
| Background: | Type de fond d'écran à utiliser dans les captures quand c'est possible (blanc, bleu, aucun).
Valeurs possibles : White, Blue, None. |
Exemple:
| Send | Receive |
| Screenshot: FilePath=/home/dan/Temp CaptureMode=fullwindow Background=None | Saved /home/dan/Temp/fullwindow001.png Screenshot finished: OK |
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:
| FirstTrack: | Un entier (0 par défaut) |
| LastTrack: | Un entier (0 par défaut) |
| TrackName: | Nom de la piste à selectionner (inutile si FirstTrack et LastTrack sont utilisés) |
| StartTime: | Un nombre en virgule flottante (0 par défaut) |
| EndTime: | Un nombre en virgule flottante (0 par défaut) |
| Mode: | Parmi: None, All, Range, Name (par défault: All) |
Exemple:
| Send | Receive |
| Select: Mode=Range FirstTrack=0 LastTrack=1 StartTime=3.2 EndTime=8.4 | Selected track 'Audio Track 1' Selected track 'Audio Track 2' Select finished: OK |
| Select: Mode=Range FirstTrack=0 LastTrack=0 StartTime=0.1 EndTime=9.9 | Selected track 'Audio Track 1' Select finished: OK |
GetPreference
Renvoie la valeur de la préférence demandée.
Parameters:
| PrefName: | Chaîne contenant le nom de la préférence (comme dans audacity.cfg) |
Exemple:
| Send | Receive |
| GetPreference: PrefName=/CsPresets/NoiseGen_Duration | 30 GetPreference finished: OK |
SetPreference
Modifie la valeur d'une préférence.
Paramètres:
| PrefName: | Chaîne contenant le nom de la préférence (comme dans audacity.cfg) |
| PrefValue: | Valeur de la préférence |
Exemple:
| Send | Receive |
| SetPreference: PrefName=/CsPresets/NoiseGen_Duration PrefValue=12.0 | SetPreference finished: OK |
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:
| TrackIndex: | Spécifie quelle piste à modifier |
| Type: | Type d'information à changer, uniquement 'Name' pour l'instant |
| Name: | Chaîne du nouveau nom de la piste |
Exemple:
| Send | Receive |
| SetTrackInfo: TrackIndex=0 Type=Name Name=Eric | SetTrackInfo finished: OK |
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:
| Filename: | Nom du fichier à importer |
Exemple:
| Send | Receive |
| Import: Filename=/home/dan/ArtTatum-Indiana.flac | Import finished: OK |
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:
| Mode: | 'All' ou 'Selection' : indique quel signal audio doit être exporté. |
| Filename: | Nom du fichier de sauvegarde. |
| Channels: | Nombre de canaux à enregistrer. |
Exemple:
| Send | Receive |
| Export: Mode=All Filename=/home/dan/ArtTatum-Indiana.mp3 Channels=2 | Exported to MP3 format: /home/dan/ArtTatum-Indiana.mp3 Export finished: OK |
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.
