Un programme Cscore peut être invoqué comme un programme autonome ou comme une partie de Csound placée entre le tri de la partition et son exécution par l'orchestre :
cscore [fichier_partition_entrée] [> fichier_partition_sortie]
ou
csound [-C] [autresoptions] [nomorch] [nompartition]
Avant d'essayer de compiler votre propre programme Cscore, vous voudrez sans
doute obtenir une copie du code source de Csound. Téléchargez la distribution des sources la plus
récente pour votre plate-forme ou bien récupérez (check out) une copie du module csound5 depuis
le CVS de Sourceforge. Il y a plusieurs fichiers dans les sources qui vous aideront. Il y a dans le
répertoire examples/cscore/ plusieurs exemples de programmes de contrôle Cscore,
y compris tous les exemples contenus dans ce manuel. Et il y a dans le répertoire frontends/cscore/
les deux fichiers cscoremain.c et cscore.c.
cscoremain.c contient une simple fonction main qui réalise
toute l'initialisation qu'un programme Cscore autonome doit faire avant d'appeler
votre fonction de contrôle. Cette « souche » main initialise Csound, lit les arguments de
la ligne de commande, ouvre les fichiers de partition en entrée et en sortie, et appelle ensuite une
fonction cscore(). Comme il est décrit ci-dessus, vous êtes chargé d'écrire la
fonction cscore() et de la fournir dans un autre fichier. Le fichier
frontends/cscore/cscore.c montre l'exemple le plus simple d'une fonction
cscore() qui lit une partition de n'importe quelle longueur et l'écrit inchangée
sur la sortie.
Ainsi, pour créer un programme autonome, écrivez un programme de contrôle en suivant les indications de la section précédente. Supposons que vous ayez sauvegardé ce programme dans un fichier nommé "mycscore.c". Vous devez ensuite compiler ce programme et le lier avec la bibliothèque de Csound et cscoremain.c pour créer un exécutable, en suivant l'ensemble de directives ci-dessous qui s'applique à votre système d'exploitation. Il sera utile d'avoir une certaine familiarité avec le compilateur C de votre ordinateur car l'information ci-dessous ne peut pas être exhaustive pour tous les systèmes existants.
Les commandes suivantes supposent que vous ayez copié votre fichier mycscore.c dans le même répertoire que cscoremain.c, que vous ayez ouvert un terminal sur ce même répertoire et que vous ayez installé au préalable une distribution binaire de Csound qui aura placé une bibliothèque libcsound.a ou libcsound.so dans /usr/local/lib et les fichiers d'en-tête pour l'API de Csound dans /usr/local/include/csound.
Pour la compilation et l'édition de liens, tapez :
gcc mycscore.c cscoremain.c -o cscore -lcsound -L/usr/local/lib -I/usr/local/include/csound
Pour l'exécution (avec envoi des résultats sur la sortie standard), tapez :
./cscore test.sco
Il est possible que sur certains systèmes Unix le compilateur C soit nommé cc ou quelque chose d'autre que gcc.
Csound est ordinairement compilé sur Windows au moyen de l'environnement MinGW qui fournit GCC -- le même compilateur utilisé sur Linux -- au travers d'un shell de commande (MSYS) à la Unix. Comme les bibliothèques pré-compilées pour Csound sur Windows sont construites de cette maniére, vous utiliserez probablement MinGW pour la liaison avec celles-ci. Si vous avez construit Csound en utilisant un autre compilateur, vous serez sans doute capable de construire également Cscore avec ce compilateur.
La compilation de programmes Cscore autonomes en utilisant MinGW devrait être similaire à la procédure ci-dessus pour Linux avec les chemins de la bibliothèque et des en-têtes changés pour pointer là où Csound est installé sur le système Windows. (Les contributions plus détaillées sur ces instructions seront les bienvenues car le rédacteur de cet article n'a pas pu tester Cscore sur une machine Windows).
Les commandes suivantes supposent que vous ayez copié votre fichier mycscore.c dans le même répertoire que cscoremain.c et que vous ayez ouvert un terminal dans ce répertoire. De plus, les outils de développement fournis par Apple (incluant le compilateur GCC) doivent être installés sur votre système et vous devez avoir installé une distribution binaire de Csound qui aura placé le framework Csoundlib dans /Library/Frameworks.
Utilisez cette commande pour la compilation et l'édition de liens. (Il peut y avoir un avertissement sur de "multiples définitions du symbole _cscore").
gcc cscore.c cscoremain.c -o cscore -framework CsoundLib -I/Library/Frameworks/CsoundLib.framework/Headers
Pour l'exécution (avec envoi des résultats sur la sortie standard) :
./cscore test.sco
Vous devrez avoir installé CodeWarrior ou un autre environnement de développement sur votre ordinateur (MPW peut fonctionner). Téléchargez la distribution des sources pour OS 9 (elle aura un nom comme Csound5.05_OS9_src.smi.bin).
Si vous utiliser CodeWarrior, trouvez et ouvrez le fichier de projet "Cscore5.cw8.mcp" dans le répertoire "Csound5.04-OS9-source:macintosh:Csound5Library:". Ce fichier de projet est configuré pour utiliser les fichiers source cscore.c et cscoremain_MacOS9.c situés dans l'arborescence des sources csound5 et la librairie partagée Csound5Lib produite lors de la compilation de Csound avec le fichier de projet "Csound5.cw8.mcp". Il vous faut substituer votre propre fichier du programme Cscore à la place de cscore.c et soit avoir compilé Csound5Lib avant, soit substituer une copie de la bibliothèque dans le projet à partir de la distribution binaire de Csound pour OS 9. Le fichier cscoremain_MacOS9.c contient du code spécialisé pour la configuration de la bibliothèque de console SIOUX de CodeWarrior et permet l'entrée d'arguments de ligne de commande avant le lancement du programme.
Une fois que les fichiers nécessaires sont inclus dans la fénêtre du projet, cliquez sur le bouton "Make" et CodeWarrior produira une application nommée « Cscore ». Quand vous lancez cette application, elle affiche d'abord une fenêtre vous permettant de saisir les arguments pour la fonction principale. Vous n'avez qu'à taper le nom de fichier ou le nom de chemin complet de la partition en entrée -- ne tapez pas "cscore". Le fichier d'entrée doit se trouver dans le même répertoire que l'application sinon vous devrez taper un chemin complet ou relatif pour le fichier. La sortie sera affichée dans la fenêtre de console. Vous pouvez utiliser la commande Save du menu File avant de quitter la console. Alternativement, dans la fenêtre de dialogue de la ligne de commande, vous pouvez choisir de rediriger la sortie dans un fichier en cliquant sur le bouton File sur le côté droit de la fenêtre de dialogue. (Notez que la fenêtre de console ne peut afficher qu'environ 32000 caractères, ce qui rend l'écriture dans un fichier nécessaire pour les grandes partitions).
Pour opérer depuis Csound, suivez d'abord les instructions pour compiler Csound (voir Construire Csound) qui concernent le système d'exploitation que vous utilisez. Une fois que vous avez réussi à construire un système Csound non modifié, substituez alors votre propre fonction cscore() à celle qui se trouve dans le fichier Top/cscore_internal.c, et reconstruisez Csound.
L'exécutable résultant est votre Csound spécial, utilisable comme ci-dessus. L'option -C invoquera votre programme Cscore après le tri de la partition d'entrée dans « score.srt ». Les détails de ce qui se passe lorsque vous lancez Csound avec l'option -C flag sont donnés dans la section suivante.
Csound 5 fournit aussi un moyen supplémentaire d'exécuter votre propre programme Cscore depuis Csound. En utilisant l'API, une application hôte peut mettre en place une fonction d'appel en retour (callback) de Cscore, qui est une fonction que Csound appellera à la place de sa fonction interne cscore(). L'avantage de cette approche est qu'il n'est pas nécessaire de recompiler la totalité de Csound. Un autre bénéfice est que l'application hôte peut choisir pendant l'exécution la fonction de callback parmi plusieurs fonctions Cscore. L'inconvénient est que vous devez écrire une application hôte.
Une approche simple pour utiliser un callback Cscore via l'API serait de modifier le programme main standard de Csound -- qui est un hôte simple de Csound -- contenu dans le fichier frontends/csound/csound_main.c. L'ajout d'un appel à csoundSetCscoreCallback() après l'appel à csoundCreate() mais avant l'appel à csoundCompile() devrait faire l'affaire. En recompilant ce fichier et en le liant à une bibliothèque de Csound existante, on obtiendra une version de Csound en ligne de commande qui fonctionne comme celle qui est décrite ci-dessus. N'oubliez pas de taper l'option -C.
Comme indiqué précedemment, les fichiers d'entrée de Cscore peuvent se trouver dans leur forme originale ou résolue en temps et pré-triée ; cette modalité sera préservée (section par section) lors de la lecture, du traitement et de l'écriture des partitions. Le traitement autonome utilisera le plus souvent des sources non résolues en temps et créera de nouveau fichiers de même forme. Lors du traitement depuis Csound, la partition en entrée arrivera déjà résolue en temps et triée, et pourra ainsi être envoyée directement (normalement section par section) à l'orchestre. Un des avantages de cette façon d'utiliser Cscore est que toutes les commodités de syntaxe du langage de partition complet de Csound peuvent être utilisées -- macros, expressions arithmétiques, carry, rampes, etc. -- car la partition passera par les phases "Carry, Tempo, Tri" du traitement avant d'être transmise au programme Cscore fourni par l'utilisateur.
Lors du traitement dans Csound, une liste d'évènements peut être transmise à un orchestre de Csound en utilisant cscoreListPlay(). Il peut y avoir n'importe quel nombre d'appels de cscoreListPlay() dans un programme Cscore. Chaque liste ainsi transmise peut-être résolue ou non en temps, mais chaque liste doit être en ordre chronologique strict par rapport à p2 (soit grâce au pré-traitement de tri soit en utilisant cscoreListSort()). S'il n'y a pas de cscoreListPlay() dans un module Cscore exécuté depuis Csound, tous les évènements écrits en sortie (via cscorePutEvent(), cscorePutString(), ou cscoreListPut()) sont envoyés dans une nouvelle partition dans le répertoire courant nommée « cscore.out ». Csound invoque alors à nouveau le tri de partition avant d'envoyer cette nouvelle partition à l'orchestre pour son exécution. La partition de sortie triée finale est écrite dans un fichier nommé « cscore.srt ».
Un programme Cscore autonome utilisera normalement la commande « put » pour écrire dans son fichier de sortie. Si un programme Cscore autonome appelle cscoreListPlay(), les évènements ainsi destinés à l'exécution seront envoyés sur la sortie comme s'ils provenaient de cscoreListPut().
Une liste de notes envoyée par cscoreListPlay() pour exécution doit être distincte dans le temps des listes de notes suivantes. Aucune fin de note ne doit dépasser la date de début de la liste suivante, car cscoreListPlay() complètera chaque liste avant d'attaquer la suivante (comme un marqueur de Section qui ne réinitialise pas le temps local à zéro). C'est important lorsque l'on utilise cscoreListGetNext() ou cscoreListGetUntil() pour charger et traiter des segments de partition avant exécution, car ces fonctions pourraient ne lire qu'un partie d'une section non triée.