Format de fichier unifié pour les orchestres et les partitions

Description

Le Format de fichier unifié, introduit à partir de la version 3.50 de Csound, permet de combiner dans le même fichier l'orchestre et la partition, ainsi que les options de ligne de commande. Le fichier a pour extension .csd. Ce format fut introduit à l'origine par Michael Gogins dans AXCsound.

Le fichier est un fichier de données structurées qui utilise un langage de balises, de la famille SGML comme HTML. Une balise ouvrante (<balise>) et une balise fermante (</balise>) servent à délimiter les différents éléments. Ce fichier est sauvegardé comme un fichier texte.

Format du fichier de données structurées

Eléments obligatoires

la première balise du fichier doit être la balise ouvrante <CsoundSynthesizer>. La dernière balise du fichier doit être la balise fermante </CsoundSynthesizer>. Cet élément sert à avertir le compilateur csound du format .csd. Tout texte situé avant la balise de début et après la balise de fin est ignoré par Csound. Cette balise peut aussi s'écrire <CsoundSynthesiser>.

Options (<CsOptions>)

Les options de ligne de commande de Csound sont insérées dans l'Elément Options. La section est délimitée par la balise ouvrante <CsOptions> et par la balise fermante </CsOptions> . Les lignes commençant par # ou par ; sont traitées comme des commentaires.

Orchestre (<CsInstruments>)

Les définitions d'instruments (orchestre) sont mises dans l'Elément Instruments. Les instructions et la syntaxe de cette section sont identiques à celles du fichier orchestre de Csound, et répondent aux mêmes besoins, y compris les instructions d'en-tête (sr, kr, etc). Cet Elément Instruments est délimité par la balise ouvrante <CsInstruments> et par la balise fermante </CsInstruments>.

Partition (<CsScore>)

Les instructions de la partition Csound sont mises dans l'Elément Score. Les instructions et la syntaxe de cette section sont identiques à celles du fichier partition de Csound, et répondent aux mêmes exigences. L'Elément Score est délimité par la balise ouvrante <CsScore> et par la balise fermante </CsScore>.

Les instructions de partition peuvent alternativement être générées par un programme externe en utilisant la balise CsScore avec un exécutable en attribut . Les lignes allant jusqu'à la balise fermante </CsScore> sont copiées dans un fichier et le programme externe nommé est appelé avec ce nom de fichier et le fichier de partition destinataire. Le programme externe doit créer une partition Csound standard.

Eléments optionnels

Inclusion de fichiers Base64 (<CsFileB>)

On peut inclure des fichiers encodés en Base64 avec la balise <CsFileB filename= nomfichier>, où nomfichier est le nom du fichier à inclure. Les données encodées en Base64 doivent se terminer par une balise </CsFileB>. Pour encoder les fichiers, on peut se servir des utilitaires csb64enc et makecsd (inclus dans Csound à partir de la version 5.00). Le fichier sera extrait dans le répertoire courant, et effacé à la fin de l'exécution. S'il existe déjà un fichier du même nom, il n'est pas écrasé, mais au contraire, une erreur est levée.

On peut inclure des fichiers MIDI encodés en Base64 avec la balise <CsMidifileB filename= nomfichier>, où nomfichier est le nom du fichier qui contient l'information MIDI. Il n'y a pas de balise fermante associée. Ceci a été ajouté dans la version 4.07 de Csound. Note : il n'est pas recommandé d'utiliser cette balise ; il vaut mieux utiliser <CsFileB>.

On peut inclure des fichiers d'échantillons encodés en Base64 avec la balise <CsSampleB filename= nomfichier>, où nomfichier est le nom du fichier qui contient les échantillons. Il n'y a pas de balise fermante associée. Ceci a été ajouté dans la version 4.07 de Csound. Note : il n'est pas recommandé d'utiliser cette balise ; il vaut mieux utiliser <CsFileB>.

Inclusion de fichiers non encodés (<CsFile>)

On peut inclure des fichiers non encodés avec la balise <CsFile filename=nomfichier>, où nomfichier est le nom du fichier à inclure. Les données doivent être suivies de la balise fermante </CsFile> seule sur sur ligne. Le fichier est extrait dans le répertoire courant et effacé à la fin de l'exécution. Si un fichier du même nom existe déjà, il n'est pas écrasé et il se produit une erreur.

Limitation de version (<CsVersion>)

On peut se limiter à certaines versions de Csound en plaçant l'une de ces instructions entre la balise ouvrante <CsVersion> et la balise fermante </CsVersion> :

Before #.#

ou

After #.#

où #.# est le numéro de version de Csound requis. La deuxième instruction peut s'écrire simplement comme :

#.#

Ceci a été ajouté dans le version 4.09 de Csound.

Information de licence (<CsLicence> ou <CsLicense>)

Des détails de licence peuvent être inclus entre la balise ouvrante <CsLicence> et la balise fermante </CsLicence>. Il n'y a pas de format pour cette information, n'importe quel texte est acceptable. Ce texte sera imprimé par Csound sur la console lorsque le CSD sera exécuté.

Information de licence (<CsShortLicence> ou <CsShortLicense>)

Depuis la version 6.05 on peut aussi inclure des détails de licence entre la balise ouvrante <CsShortLicence> et la balise fermante </CsShortLicence>. Cet option concerne sept licences bien connues, encodée par un entier.

0 : "Tous droits réservés" (valeur par défaut)
1 : "Creative Commons Attribution-NonCommercial-NoDerivatives (CC BY-NC-ND)"
2 : "Creative Commons Attribution-NonCommercial-ShareAlike (CC BY-NC-SA)"
3 : "Creative Commons Attribution-NonCommercial (CC BY-NC)"
4 : "Creative Commons Attribution-NoDerivatives (CC BY-ND)"
5 : "Creative Commons Attribution-ShareAlike (CC BY-SA)"
6 : "Creative Commons Attribution-ShareAlike (CC BY)"
7 : "Sous licence BSD"

HTML imbriqué (<html>)

Tout code HTML valide peut être imbriqué dans un fichier CSD. Ce code doit être structuré exactement comme dans une page Web ordinaire. Il peut contenir tout code HTML, Javascript, Cascading Style Sheet, WebGL, etc., valide.

Dans certains frontaux et environnements de programmation, comprenant au moins CsoundQt ou Csound pour Android, cette page sera analysée, exécutée et affichée dans un navigateur Web embarqué dans l'environnement. Le code Javascript de cette page aura accès à un objet csound global qui implémente les fonctions suivantes qui forment un sous-ensemble de l'API de Csound. Les noms, les types de données et l'utilisation de ces fonctions sont exactement les mêmes que ceux qui sont détaillés dans le manuel de référence de l'API de Csound.

[int] getVersion ();
compileOrc (orchestra_text);
[double] evalCode (orchestra_expression);
readScore (score_text);
setControlChannel (channel_name, numeric_value);
[double] getControlChannel (channel_name);
message (message_string);
[int] getSr ();
[int] getKsmps ();
[int] getNchnls ();
// Ne fait pas partie de l'API de Csound -- appelé par l'environnement pour
// détecter si Csound est en cours d'exécution.
[int] isPlaying ();
            

Les éléments HTML du fichier CSD peuvent être utilisés pour créer des interfaces utilisateur personnalisées pour la pièce, pour générer des évènements de partition et même du code d'orchestre en utilisant Javascript, pour stocker des préréglages des contrôleurs graphiques et pour bien d'autres fonctions. Les exemples GameOfLife3D.csd et LindenmayerCanvas.csd démontrent ces utilisations (testés dans CsoundQt ; l'exécution de ces exemples nécessitent des ressources supplémentaires que l'on trouve dans le répertoire des exemples de Csound dans GIT).