# Manuel de RaySession

pour la version 0.13.1

## Introduction

RaySession est un gestionnaire de session audio pour GNU/Linux. Il permet de démarrer dans une même session plusieurs programmes audio, de sauvegarder leurs projets ensemble et ainsi d’éviter de multiples manipulations pour retourner à une configuration donnée.

Pour être lancés dans RaySession, il est très largement préférable que ces programmes audio soient compatibles avec le protocole NSM, et beaucoup le sont déjà, entre autres Ardour, Qtractor, Carla, Guitarix, Mamba, Patroneo, ZynAddSubFx…​

RaySession part du principe que votre configuration audio est fonctionnelle pour de la production audio, si ce n’est pas le cas réglez d’abord ce problème et ne perdez pas votre temps à essayer d’utiliser RaySession.

Maintenant voyons comment s’en servir.

## Exemple d’utilisation simple

Pour la production audio sous GNU/linux, Il est largement conseillé d’utiliser le serveur JACK. Avant de créer ou de lancer une session, assurez-vous que le serveur JACK tourne, RaySession n’a aucun rapport direct avec JACK, toutefois les programmes que vous allez lancer dans votre session en auront besoin.

Prenons un exemple où pour composer un morceau, nous aurons besoin des logiciels Ardour et Guitarix, assurez vous que ces 2 programmes soient installés.

Pour créer une nouvelle session, cliquez en haut à gauche sur Nouvelle Session (ou Ctrl+N). Apparaît alors une fenêtre de dialogue.

En haut à droite vous apercevez le dossier racine des sessions, c’est là que les sessions seront sauvegardées (une session RaySession étant un dossier contenant un fichier `raysession.xml`).

Rentrez le nom voulu pour cette nouvelle session dans le champ prévu à cet effet. Pour mettre votre nouvelle session dans un sous-dossier, tapez le nom de la manière suivante : `sous-dossier/ma session` .

La boîte à choix multiples de modèles de session vous permet de choisir entre

- Un modèle de session vide

- Un modèle avec mémoire des connexions JACK

- Un modèle scripté avec mémoire de la configuration de JACK

- Un modèle avec les scripts de session de base (pour les utilisateurs avancées pourvus de connaissances en script shell)

- Tous les modèles de session que vous aurez vous-même créés.

Dans un premier temps, laissez le modèle sur Avec mémoire du patch de JACK, cliquez sur Ok pour lancer votre session.

La partie session de la fenêtre devient active, en haut est écrit le nom de votre session, et votre session contient déjà un programme client qui s’appelle Connexions JACK. C’est lui qui sauvegardera et refera les connexions de la baie de brassage de JACK.

Pour ajouter Ardour à votre session, cliquez sur le bouton Application (ou Ctrl+A), apparaît alors la fenêtre des applications (plus de détails à la rubrique Fenêtre d’ajout d’application). Dans la partie droite, cherchez Ardour (selon votre version d’ardour, il est possible qu’il s’appelle Ardour5 ou Ardour6) et double-cliquez dessus.

Un client Ardour apparaît en dessous de Connexions JACK et Ardour démarre (normalement directement avec une session Ardour vide).

Faites de même avec Guitarix.

Dans Ardour, ajoutez une piste (Menu: Piste → Ajouter une piste), dans la fenêtre Ardour qui est apparue, nommez la piste Guitare et mettez la boîte à choix multiples configuration sur Stereo.

Servez-vous maintenant de la Baie de brassage de JACK qui occupe la partie droite de la fenêtre de RaySession. Connectez l’entrée de Guitarix à une entrée matérielle et les sorties de Guitarix vers les entrées de cette nouvelle piste Ardour. Assurez vous que les entrées de votre piste Guitare ne sont pas connectées aux entrées matérielles.

Voilà, vous avez une configuration où vous pouvez enregistrer directement le son de votre guitare traité par Guitarix dans Ardour. Si vous n’avez pas de guitare, vous n’avez qu’à chanter faux dans un micro ou taper sur un coussin, ce n’est ici qu’un exemple.

Sauvegardez la session en cours en cliquant sur le bouton en forme de disquette vers le haut à droite de la partie Session (ou Ctrl+S). Il est vivement recommandé car très pratique d’affecter un raccourci clavier global de votre système à la sauvegarde de la session en cours. Celà dependra de votre environnement de bureau, mais il suffit d’affecter le raccourci Ctrl+Meta+S à la commande `ray_control save` (Meta est la touche Windows), ainsi vous n’aurez pas à retourner à la fenêtre de RaySession pour sauvegarder la session.

Maintenant, fermez la session en cliquant sur la croix rouge en haut à droite de la partie Session(ou Ctrl+W).

Une fois la session fermée, cliquez sur Ouvrir une session (ou Ctrl+O), double-cliquez sur la session que vous venez de créer pour la ré-ouvrir.

Vous devez retrouver les programmes et leur projet ainsi que les connexions de JACK telles qu’elles étaient quand vous avez fermé la session, et tout fonctionne donc sans aucune autre manipulation.
Un des avantages de la modularité dans ce cas précis, c’est qu’une fois qu’on aura terminé les prises de guitare, on pourra arrêter Guitarix pour ne pas surcharger le processeur inutilement, et il sera tout de même facile de le redémarrer si besoin.

## Vue d’ensemble des outils de la session

### Ligne du haut

De gauche à droite:

- le bouton menu vous donne accès à

  - sauvegarder la session en cours comme modèle
    Le modèle de session créé apparaîtra alors dans la boîte à choix multiples de modèles de session dans la fenêtre de dialogue Nouvelle Session. Attention toutefois, L’ensemble des fichiers de la session seront sauvegardés dans le modèle, il ne faut donc pas le faire si la session contient beaucoup de fichiers audios. D’une part la copie sera longue, d’autre part vous risquez de multi-copier inutilement des fichiers qui prendront beaucoup de place.

  - Dupliquer la session en cours
    C’est l’équivalent du bien connu "Sauvegarder sous…​", sauf que RaySession est obligé d’arrêter et de redémarrer la plupart des programmes pour passer d’une session à l’autre. Évitez de dupliquer une session avec beaucoup de fichiers audios, celà pourrait être long, mais fort heureusement une telle opération peut être annulée.

  - Renommer la session
    Il faudra alors arrêter tous les clients.
    Alternativement, vous pouvez renommer une session en la dupliquant puis en supprimant le dossier de la session initiale.
    Vous pouvez aussi renommer une session en renommant son dossier, mais ATTENTION, cette session ne doit surtout pas être chargée !

- le bouton en forme de crayon vous donne accès aux notes de session.
  Écrivez ici des informations dont vous avez besoin, des réglages physiques, les paroles d’une chanson, la recette du cassoulet de mamie…​toutefois n’y écrivez pas un roman en 3 tomes, d’autres outils sont bien plus adaptés, et les notes sont limitées à 65000 caractères pour des raisons techniques.
  Le crayon est vert quand des notes existent, il est orange quand la fenêtre de notes est ouverte, sinon il est transparent.

- le nom de la session chargée (ici ma session)

- le bouton Abandonner la session qui permet de fermer la session sans la sauvegarder

- le bouton Fermer la session, qui sauvegarde et ferme la session en cours.
  Notez que vous n’avez pas besoin de fermer la session en cours pour en ouvrir une autre. Certains clients sont capables de basculer d’une session à l’autre et ça peut être beaucoup moins long que de tout fermer pour tout relancer.

### Ligne du bas

De gauche à droite:

- le bouton en forme de dossier pour ouvrir le dossier de la session avec votre gestionnaire de fichiers

- le bouton en forme d’étoile jaune qui déroule un menu contenant vos applications favorites s’il y en a

- le bouton Application qui permet d’ajouter à la session un modèle d’application d’usine ou que vous aurez créé vous même. C’est la méthode conseillée pour ajouter un client. voir Fenêtre d’ajout d’application.

- le bouton Exécutable qui permet d’ajouter à la session un programme depuis son exécutable. Vous en aurez besoin si vous souhaiter ajouter un programme pour lequel il n’existe pas de modèle. voir Fenêtre d’ajout d’exécutable.

- le bouton de marche arrière pour revenir à un état précédent de la session. Celà nécessite d’avoir le programme `git` installé, sinon ce bouton n’apparaîtra pas.
  Voir Les clichés pour plus de détails.

- l’indicateur d’état du serveur.
  Les états du serveur peuvent être en réalité très furtifs, mais ils sont affichés pendant un temps suffisament long pour que vous puissiez les voir.
  L’état du serveur peut être:

  - éteint : pas de session en cours

  - prêt : la session est en cours

  - lancement : lancement des programmes de la session

  - copie : une copie est en cours, pour une duplication de session ou une sauvegarde de la session comme modèle

  - fermeture : la session est en train de se fermer

  - cliché : un cliché de la session est en train d’être pris, donc vous pourrez revenir à l’état actuel la session.
    voir Les clichés.

  - attente : Le serveur attend que vous fermiez vous-même des programmes non sauvegardables

  - script : un script est actionné

  Une fenêtre d’information ou de progression s’affiche si vous cliquez sur cet indicateur d’état s’il est sur copie, cliché ou attente.

- le bouton de sauvegarde de la session

- la corbeille, vous trouverez ici les clients que vous avez supprimés. Vous pourrez alors les restaurer dans la session ou supprimer définitivement tous les fichiers qu’ils ont créé dans le dossier de la session.

## Vue d’ensemble d’un client

Un client contient de gauche à droite:

- L’icône du client sur laquelle vous pouvez cliquer pour faire apparaître un menu avec les actions suivantes

  - Sauvegarder comme modèle d’application
    Le modèle créé apparaîtra alors dans la Fenêtre d’ajout d’application. Celà permet par la suite de lancer directement un client avec la configuration souhaitée (Ardour avec telles pistes, Hydrogen avec tel kit de batterie…​). Attention, celà copie tous les fichiers du client donc évitez de le faire si le client contient beaucoup de fichiers audio.

  - Renommer
    Changer le nom du client situé à droite de son icône, il s’agit d’un nom purement visuel qui peut vous aider à retrouver vos moutons

  - retourner à un état précédent
    Permet de faire revenir uniquement le client à un état antérieur de la session, voir Les clichés.
    Vous ne pourrez toutefois pas revenir à un état antérieur à un renommage de la session, pour celà il faut faire revenir toute la session en arrière.

  - Propriétés
    Affiche la fenêtre des propriétés du client

  Ce menu est aussi accessible par clique droit n’importe où sur le client

- Le nom du client (ici Carla), qui peut-être changé facilement par clique droit → renommer

- selon le type et les capacités du client vous pouvez voir ici

  - un oeil (éventuellement barré), celà signifie que le client est compatible NSM et qu’il est capable d’afficher ou cacher sa fenêtre en cliquant sur l’oeil.

  - un bouton Hack, celà signifie que le client n’est pas compatible NSM, en tout cas qu’il n’est pas lancé avec ce protocole. Cliquer sur Hack permet de changer la façon dont il est lancé en ouvrant la fenêtre de propriétés du client sur l’onglet Ray-Hack

- Le bouton Démarrer qui est grisé si le client est déjà démarré

- le bouton Arrêté qui est grisé si le client n’est pas démarré. Si vous arrêtez le client et qu’il n’est toujours pas arrêté après un certain temps, le bouton devient rouge et vous pouvez cliquer dessus pour tuer le client. Mais restez détendus, et ne l’utilisez que si vraiment il vous semble complètement inerte, celà pourrait causer des problèmes, même si a priori personne ne vous enverra en prison.

- l’état du client qui peut être

  - arrêté : le client est arrêté

  - prêt : il est lancé et fonctionnel

  - ouverture : le programme est en train d’ouvrir son projet, patientez un peu

  - fermeture : le programme est en train de se fermer

  - lancé : s’il reste sur l’état lancé, celà signifie

    - si c’est un client Ray-Hack, qu’il n’a pas de fichier de configuration

    - s’il est lancé comme un client NSM, qu’il n’est pas compatible NSM, et qu’ainsi toute sauvegarde est vaine. Il peut être pratique de lancer de cette façon certains programmes tels qu’une baie de brassage (Catia) ou un utilitaire dont on n’a pas besoin de sauvegarder l’état (Qrest).

  - bascule : le client change de projet pendant un changement de session

- le bouton en forme de disquette qui permet de sauvegarder le client.
  Si par dessus cette disquette vous voyez

  - trois points rouges: le client contient des changements non sauvegardés

  - un V vert: le client ne contient pas de changements non sauvegardés

  - un point d’exclamation orange: Ce n’est pas un client NSM, et il est impossible de sauvegarder son projet, vous devrez le faire vous même

- la croix rouge qui permet d’envoyer le client à la corbeille

## Fenêtre d’ajout d’application

Le fenêtre d’ajout d’application se lance en cliquant sur le bouton Application (ou Ctrl+A).

La liste des applications disponibles est à droite. Si le logiciel que vous souhaitez lancer n’est pas présent ici, regardez Ajouter un programme non fourni.

En haut à gauche, c’est le bloc de filtres

- le champ de filtre permet de rentrer une chaîne de caractères, seuls les modèles contenant cette chaîne de caractères dans leur nom apparaîtront.

- la case à cocher Usine affiche les modèles intégrés à RaySession ou fournis par votre distribution

- utilisateur affiche les modèles créés par l’utilisateur en faisant Sauvegarder comme modèle d’application

- NSM affiche les clients compatibles NSM, ou lancés comme tel (voir Ajouter un programme non fourni)

- Ray-Hack affiche les clients lancés sans protocole NSM

En bas à gauche le bloc d’informations sur le modèle sélectionné à droite

- en haut à droite de ce bloc, une étoile, cliquez dessus pour l’ajouter aux favoris ou l’enlever des favoris

- Si c’est un modèle utilisateur, un bouton Utilisateur vous permet de supprimer ce modèle

- le bouton en bas à droite de ce bloc vous permet d’accéder à toutes les propriétés du modèle, comme dans la Fenêtre de propriétés d’un client, sauf que rien n’est éditable.

Astuce : Cette fenêtre est conçue pour un ajout d’application très rapide, et se comporter comme Alt+F2 sur votre bureau.
Par exemple, depuis la fenêtre principale de RaySession, pour ajouter Carla tapez Ctrl+A, puis `carla`, sélectionnez le bon modèle avec les flèches Haut/Bas, puis Entrée.

## Fenêtre d’ajout d’exécutable

Le fenêtre d’ajout d’exécutable se lance en cliquant sur le bouton Exécutable (ou Ctrl+E).

Vous aurez besoin de passer par cette fenêtre si vous voulez ajouter un client qui n’apparaît pas dans la liste de la fenêtre d’ajout d’application. Cette fenêtre se présente très simplement, un champ pour rentrer l’exécutable, une case Protocole NSM, un bouton d’options avancées.

Laissez le protocole NSM coché si:

- le programme à lancer est compatible NSM (s’il n’est pas dans la liste d’applications, merci de le faire savoir !)

- le programme à lancer est un utilitaire dont on n’a aucun besoin de sauvegarder un quelconque projet (QRest, Catia…​).
  L’état d’un tel programme restera sur lancé et ne sera jamais prêt, c’est sans importance vu qu’ils n’a pas de projet à sauvegarder.

Si vous laissez le protocole NSM coché il ne sera pas possible d’ajouter un exécutable vers un chemin absolu, l’exécutable doit se situer dans un emplacement prévu à cet effet (vous ne pourrez pas lancer `/usr/bin/mon_programme`, mais `mon_programme`). Vous ne pouvez pas rentrer d’arguments ici, avec ou sans le protocole NSM.

Décocher la case Protocole NSM revient à lancer le programme avec le pseudo-protocole Ray-Hack.

Si vous cliquez sur le bouton d’options avancées, un bloc options avancées apparaît avec

- la case Démarrer le client, si vous la décochez le client sera ajouté mais non lancé

- la boîte à choix multiple Mode de préfixe, celà définit le préfixe du nom des fichiers du client

  - sur Nom de la session, les noms des fichiers commenceront par le nom de la session, c’est la valeur par défaut

  - sur Nom du Client, les noms des fichiers commenceront par le nom fourni par le client lui-même, comme c’est le cas avec New Session Manager

  - sur Personnalisé, les noms des fichiers commenceront par la valeur que vous inscrirez dans le champ Préfixe juste en dessous

- le champ Préfixe qui n’est actif que si Mode de Préfixe est sur Personnalisé

- le champ ID du client (identifiant du client). Ne rentrez ici que des caractères alphanumériques ou des '_'.
  Celà est utile si vous voulez attraper et lancer des projets existants dans la session avec un exécutable. C’est pratique si vous voulez charger dans la session des projets créés en dehors d’une session. Aucune méthode ne permet de rendre la chose plus simple, celà dépend énormément du programme utilisé. RaySession vous insultera si vous rentrez un identifiant de client qui existe déjà dans la session.

- la case à cocher Longs noms de client JACK. Si cette case est cochée, les clients seront supposés utiliser `NomDuProgramme.Identifiant` comme motif pour leurs clients JACK, sinon ce sera `NomDuProgramme` éventuellement suivi de `_N` (ou N est un nombre). C’est tout à fait pratique si vous utilisez de multiples instances d’un même programme, et que vous souhaitez pouvoir facilement les reconnaître dans la baie de brassage.

## Baie de brassage

Manuel de la baie de brassage

la baie de brassage de JACK est affichée par défaut. Vous pouvez la cacher en cliquant sur Contrôle puis en décochant Afficher la baie de brassage de JACK (ou Ctrl+J). La baie de brassage contient tous les ports AUDIO et MIDI de JACK que vous pouvez interconnecter.

Évidemment, si JACK n’est pas démarré, cette baie de brassage sera vide.

Il est conseillé d’avoir le pont A2J lancé si vous voulez travailler correctement avec le MIDI. Vous pouvez configurer celà via Cadence, Studio Control, ou via l’utilitaire en ligne de commande `a2j_control`.

RaySession n’inclut pas d’outils pour configurer le serveur JACK, QJackCtl, Studio Control, Cadence, ou l’utilitaire en ligne de commande `jack_control` font très bien ce travail. Notez que cette baie de brassage fonctionne également avec PipeWire.

Beaucoup plus d’infos sur la baie de brassage sont sur Le manuel de la baie de brassage.

## Fenêtre de propriétés d’un client

La fenêtre de propriétés d’un client s’ouvre depuis le menu du client, en cliquant sur Propriétés.

La fenêtre des propriétés du client comprend 2 onglets, un onglet Général et un onglet spécifique au protocole utilisé par le client. Selon le protocole du client, le deuxième onglet s’appelle NSM, Ray-Hack ou Ray-Net.

### Onglet Général

- Le premier bloc de l’onglet Général affiche l’identifiant, le protocole, l’étiquette, la description et l’icône du client.
  Si vous ne les éditez pas, l’étiquette, la description et l’icône sont tirées du fichier .desktop associé à l’exécutable lancé, s’il a été trouvé.
  Si vous tenez à connaître le fichier .desktop utilisé, tapez `ray_control client IDENTIFIANT get_properties` dans un terminal (en remplaçant IDENTIFIANT par l’identifiant du client).

- Ensuite vient le bloc des clichés, voir Les clichés.

- la case à cocher Empêcher l’arrêt sans sauvegarde récente ou possible concerne la fenêtre qui peut apparaître lorsque vous demandez à un client de s’arrêter. Si cette case est décochée, alors le client sera stoppé sans qu’une fenêtre ne vous prévienne.
  Si la case est cochée, la fenêtre vous previendra lorsque

  - le client est non-sauvegardable depuis RaySession

  - on sait que le client contient des changements non sauvegardés

  - le client semble ne pas avoir été sauvegardé depuis plus d’une minute

  cocher cette case ou non dépend seulement de l’importance de la sauvegarde de votre client, à vous de juger. Celà dit, si la fenêtre d’avertissement vous agace, vous n’aurez qu’à cocher la case Ne plus empêcher l’arrêt du client dans cette fenêtre et la case Empêcher l’arrêt sans sauvegarde récente ou possible sera décochée.

### Onglet NSM

Le nom du client ici est fourni par le client lui-même.
Les capacités sont celle qui sont transmises par le client à son démarrage. Si le client n’a pas encore été démarré, ce champ est donc vide.

Éditer l’exécutable permet de changer la commande qui lance le client. Ne le changez que pour un autre exécutable capable de charger le projet du client existant. C’est utile par exemple si vous avez deux versions d’Ardour, l’une se lançant avec la commande `ardour`, l’autre avec `Ardour6`, et que vous voulez changer la version à utiliser.

Éditer les arguments est fortement déconseillé, et n’est surtout pas adapté au chargement d’un fichier comme argument.

### Onglet Ray-Hack

Si le client est de type Ray-Hack, ici moult champs s’offrent à vous. Ce n’est pas forcément une bonne nouvelle, l’idée est de pouvoir charger dans la session un programme qui n’est pas (encore) compatible NSM. S’il est bien implémenté dans le client, le protocole NSM sera toujours bien plus confortable à utiliser et plus fiable que cette bidouille. Ceçi dit, si l’on peut attendre l’implémentation NSM dans tous les programmes audio, ce n’est pas le cas des autres programmes qui peuvent tout de même avoir une utilité dans la session.

Le pseudo-protocole Ray-Hack reprend les attributs des proxy (nsm-proxy ou ray-proxy), sauf que le client est lancé directement dans la session.

#### Bloc de lancement

- le Dossier est le nom du dossier de ce client, dans le dossier de la session. Le programme est lancé depuis ce dossier.

- L'Exécutable est la commande qui lance le programme

- Le Fichier de configuration sera le fichier du projet qu’on souhaitera ouvrir avec ce programme. Il plus que très recommandé de faire référence à un fichier dans le dossier du client.
  La variable `$RAY_SESSION_NAME` sera automatiquement remplacée par le nom de la session.
  Si ce champ est vide, le client restera toujours sur le statut lancé et jamais prêt. Dans certains cas, il peut donc être utile de taper n’importe quoi ici plutôt que rien.

- Le bouton Naviguer ouvre une boîte de dialogue pour aller chercher le fichier de projet et remplir le champ Fichier de configuration

- Le champ Arguments comprend les arguments passés à la commande Exécutable
  les arguments sont découpés comme ils le seraient dans un terminal, n’oubliez pas les " ou les ' si nécéssaire.
  par exemple pour reproduire `ma_commande mon_argument_1 "mon argument 2"` rentrez `ma_commande` dans le champ Exécutable et `ma_commande mon_argument_1 "mon argument 2"``dans le champ Arguments.

#### Bloc des signaux

- Le Signal de sauvegarde ne peut être que rarement utilisé. Il peut être SIGUSR1 pour les programmes compatibles avec le vieux protocole LASH. Sinon laissez le sur Aucun, s’il n’y a pas de méthode de sauvegarde, on ne peut pas l’inventer.

- Le Signal d’extinction sera généralement SIGTERM. Ne le changez qu’au cas où ce signal ne ferme pas correctement le programme.

- si la case Attendre une fenêtre avant d’être considéré comme prêt est cochée, alors le statut du client ne passera sur prêt que lorqu’une fenêtre apparaitra.
  Si `wmctrl` n’est pas installé, ou que le gestionnaire de fenêtres ne semble pas compatible avec, alors le client passera sur prêt une demi-seconde après son lancement.

Avec `ray_control` vous pouvez affecter d’autres signaux que ceux proposés dans les boîtes à choix multiple. Par exemple
`ray_control client CLIENT_ID set_properties save_sig:22`
définira le signal SIGTTOU pour la sauvegarde du client CLIENT_ID. Tapez `kill -l` pour connaître les signaux disponibles et leurs numéros.

#### Bloc de gestion des non-sauvegardables

Ce bloc n’est actif que si le Signal de sauvegarde est reglé sur Aucun

- si la case Demander à l’utilisateur de fermer lui-même le programme à la fermeture de la session est cochée, le client sera alors considéré comme non sauvegardable et un point d’exclamation orange apparaitra devant son icône de sauvegarde. À la fermeture de la session, RaySession attendra que vous fermiez vous-même le programme car il est impossible de savoir s’il contient des changements non sauvegardés.

- Si la case Essayer de fermer gracieusement la fenêtre est cochée, alors à la fermeture de la session, RaySession essaiera de fermer la fenêtre comme si vous fermiez la fenêtre du programme. C’est très pratique lorsque le programme réagit en se fermant s’il n’y a pas de changements non sauvegardés et en affichant une fenêtre de confirmation de fermeture dans le cas inverse (la plupart des programmes réagissent de la sorte). Si `wmctrl` n’est pas installé ou que le gestionnaire de fenêtres ne semble pas compatible, vous devrez fermer le programme vous même dans tous les cas.

#### Zone de test

La zone de test vous permet de tester les réglages de lancement, d’arrêt et de sauvegarde réglés dans cette fenêtre sans avoir à Sauvegarder les changements.

## Les sessions réseau

Une session réseau permet de lancer une autre session sur une autre machine en même temps que votre session. Ça peut être particulièrement utile si vous utilisez net-jack pour décharger votre machine d’une partie du DSP, si vous avez des effets gourmands qui tournent sur une autre machine par exemple.

Les sessions réseau fonctionnent selon un rapport de maître à esclave. Une session est maîtresse et peut avoir plusieurs sessions esclaves elles-mêmes maîtresses d’autres esclaves, mais un tel scénario semble complètement farfelu. Organisez vous simplement: un maître, un ou des esclave(s).

Pour lancer une session réseau (esclave donc), lancez le modèle d’application Network Session depuis la fenêtre des applications et suivez les instructions.

Vous devrez lancer un démon sur la machine distante avec la commande `ray-daemon -p 1234` (`1234` est un exemple, mettez le port que vous voulez). Ce démon vous affiche dans le terminal quelque chose sous cette forme:

    [ray-daemon]URL : osc.udp://192.168.1.00:1234/
    [ray-daemon]      osc.udp://nom-de-machine:1234/
    [ray-daemon]ROOT: /home/utilisateur/Ray Sessions reseau

Vous devrez copier dans la fenêtre d’invitation de la session réseau l’une des deux URLs. La première (qui commence par `osc.udp://192.168.`) doit fonctionner à coup sûr, la seconde ne fonctionnera que si le nom de la machine esclave est correctement renseigné dans le fichier `/etc/hosts` de la machine maître. Toutefois, renseigner le nom de la machine esclave dans `/etc/hosts` et utiliser la deuxième URL est préférable, parce que l’adresse en 192.168. bougera si vous branchez votre machine esclave différemment (en filaire, en wifi), ou si vous réinstallez la distribution.

Vous avez à présent 2 fenêtres RaySession sur votre machine maître, l’une contrôle la session maître, l’autre l’esclave. Vous reconnaîtrez l’esclave au fait qu’elle n’a ni barre d’outils (Nouvelle Session, Ouvrir une session, Contrôle), ni boutons Abandonner la session et Fermer la session.

La fenêtre esclave est cachable comme c’est le cas dans beaucoup de programmes NSM.

Si vous lancez `raysession -p 1234` sur votre machine esclave, vous aurez la fenêtre de la session esclave en double exemplaire, une sur chaque machine.

Conseil: Mettez ce `ray-daemon -p 1234` au démarrage de votre machine esclave.

## Ajouter un programme non fourni

Si le programme que vous voulez ajouter ne gère pas de projet à enregistrer, cliquez sur Exécutable, rentrez le nom de l’exécutable et cliquez sur Ok. Sinon suivez cet exemple.

Nous voulons ajouter ici Audacity à la session. Audacity est choisi à titre d’exemple parce qu’il est connu et généralement installé sur les distributions audio. Ce n’est pas forcément un programme très adapté à la modularité d’une session audio étant donné la façon dont il gère JACK.

Cliquez sur Exécutable (ou Ctrl+E).
Dans la fenêtre d’ajout d’exécutable, Décochez la case Protocole NSM, tapez `audacity` dans le champ d’exécutable et cliquez sur Ok.

Un nouveau client est créé, sa fenêtre de propriétés s’ouvre sur l’onglet Ray-Hack et Audacity se lance.

Dans Audacity, nous allons directement sauvegarder un projet vide dans le dossier du client. Le dossier du client se trouve dans le dossier de la session et porte le nom donné après Dossier: tout en haut de l’onglet Ray-Hack. Nous allons appeler le projet EXACTEMENT comme la session RaySession en cours. Pour celà, dans Audacity, faites Menu → Fichier → Sauvegarder le projet → Sauvegarder le projet.

Cliquez sur Valider à l’éventuelle fenêtre d’avertissement.
Dans la boîte de sauvegarde de fichiers qui s’ouvre, vous trouverez le dossier de la session en bas à gauche (voir Fournir des raccourcis du dossier de la session), cliquez dessus pour rentrer dedans. À l’intérieur de celui-ci vous devez voir le dossier du client tel qu’il figure en haut de l’onglet Ray-Hack, rentrez dans ce dossier. En haut à gauche de la boîte de sauvegarde, tapez le nom exact de votre session dans le champ Nom: puis validez.

Fermez Audacity.
En haut à droite de l’onglet Ray-Hack de la fenêtre de propriétés du client, cliquez sur Naviguer.

sélectionnez le projet Audacity que vous venez de créer, son nom commence par le nom de la session et termine par `.aup`.

Si tout s’est bien passé, le champ Fichier de configuration est devenu `$RAY_SESSION_NAME.aup` et le champ Arguments est devenu `"$CONFIG_FILE"`.
Cochez les cases Attendre une fenêtre avant d’être considéré comme prêt, Demander à l’utilisateur de fermer lui même le programme et Essayer de fermer gracieusement la fenêtre. Cliquez en bas à droite sur Sauvegarder les changements.

Lancez le client Audacity et vérifiez que la fenêtre d’Audacity porte bien le nom de la session.
Cliquez sur l’icône du client Audacity, dans le menu déroulant choisissez Sauvegarder comme modèle d’application, et rentrez `Audacity` dans le champ de la boîte de dialogue qui est apparue. Maintenant lorsque vous voudrez lancer Audacity dans la session, vous n’aurez qu’à lancer le modèle Audacity depuis la fenêtre d’ajout d’applications.

Notez que le bouton de sauvegarde du client est derrière un point d’exclamation orange, celà signifie que RaySession n’est pas en mesure de sauvegarder son projet et qu’il faudra le faire vous même.

Selon le programme que vous souhaitez ajouter à la session, il est possible que ce ne soit pas toujours aussi facile. Certains programmes vont exiger un argument qui précède le fichier de configuration, dans ce cas tapez `mon_programme --help` ou `man mon_programme` pour savoir comment charger un projet au démarrage du programme, et adaptez celà dans le champ Arguments.

## Importer une session NSM

Pour importer une session créée avec Non Session Manager ou New Session Manager, déplacez ou copiez le dossier de la session dans le dossier racine des sessions RaySession (par défaut ~/Ray Sessions). Ensuite cliquez sur Ouvrir une session, votre session doit apparaître dans la liste des sessions, double-cliquez dessus.

RaySession ne ré-écrira pas les clients ajoutés ou supprimés dans la fichier session.nsm, à partir du moment où vous ouvrez une session NSM avec RaySession, vous devez continuer avec RaySession.

Si jamais vous souhaitez utiliser un autre gestionnaire de sessions, vous trouverez dans le menu Fichier → Utilitaires → Convertir la session au format NSM qui - comme son nom l’indique - convertit la session en cours au format de session NSM. Évidemment, celà entraîne quelque modifications, tels que le mode de préfixe ou la façon dont seront nommés les clients JACK, mais rien qui empêche la session de fonctionner.

## Les options du démon

Les options du démon sont des services qui sont activables et désactivables via le bouton Contrôle en haut à droite de la fenêtre principale, ou via le menu options de la barre de menus.

Voici le détail des différentes options:

### Fournir des raccourcis du dossier de la session

En production audio, on a souvent recours au fait de créer un fichier audio ou midi avec un programme pour finalement le charger dans un autre. Cette option offre quelque chose de purement pratique: un raccourci vers le dossier de la session en cours dans votre gestionnaire de fichiers et dans les boîtes de dialogue prévues pour aller chercher ou sauvegarder les fichiers. Ça permet tout simplement d’éviter de perdre du temps à parcourir l’arborescence de son dossier personnel pour chercher un fichier que vous avez mis dans le dossier de votre session puisque c’est bien sa place.
Bien entendu, ce raccourci est supprimé lorsque la session est déchargée.
Techniquement, les raccourcis sont créés pour GTK2, GTK3, QT4, QT5, KDE et FLTK.

### Cliché automatique à la sauvegarde

Cette option est très loin d’être triviale, elle permet de prendre un cliché de la session après chaque sauvegarde. Celà signifie qu’en cas d’erreur technique ou artistique vous aurez la possibilité de retrouver la session dans l’état où elle se trouvait au moment du cliché. Cette option nécessite d’avoir le programme `git` installé. Voir Les clichés pour plus de détails.

### Mémoire des bureaux

Si cette option est enclenchée, RaySession sauvegardera (ou tentera de sauvegarder) le numéro du bureau virtuel sur lequel se trouvaient les fenêtres des clients à la sauvegarde de la session.
Ainsi lorsque vous relancerez la session ou les clients, les fenêtres seront redispatchées sur les bureaux sur lequels elles figuraient.
Cette option nécessite d’avoir le programme `wmctrl` installé pour fonctionner, et ne fonctionnera probablement pas avec Wayland.

### Scripts de session

Désactiver cette option pour n’actionner aucun script de session, et ainsi ouvrir, sauvegarder ou fermer une session en ignorant totalement les scripts associés à ces actions.
Ces scripts sont utilisés par les sessions avec Mémoire de la configuration de JACK.
Voir Les scripts de session pour plus de détails.

### Se souvenir de l’état des IGUs

Cette option ne concerne que les client NSM capables d’afficher/cacher leur interface graphique. Sans cette option, certains d’entre eux vont toujours démarrer cachés, d’autres vont se souvenir s’ils étaient visibles à leur dernière sauvegarde. Avec cette option enclenchée, les interfaces graphiques seront affichées au moment où la session est prête si elles étaient visibles lors de la dernière sauvegarde ou si le client n’a jamais été lancé.

## Les clichés

Les clichés nécessitent d’avoir le programme `git` installé, si vous n’avez pas `git`, le bouton de marche arrière n’apparaît pas et il est impossible de prendre un cliché ou d’y revenir.

Un cliché mémorise les fichiers et leurs contenu à un moment précis. Les fichiers volumineux et les fichiers ayant certaines extensions tels que les fichiers audio et video sont ignorés, sinon le processus de cliché serait trop long et celà doublerait inutilement la taille des dossiers de session. Celà n’est en fait pas très gênant, au contraire, puisque vos fichiers audio récents restent présents quand vous retournez à un cliché précédent.
Si malgré tout le processus de cliché s’avère long, une fenêtre apparaît et vous pouvez annuler sans aucun risque le cliché en cours. Si vous l’annulez, Le cliché automatique n’aura plus lieu pour cette session.

L’intérêt des clichés réside dans le fait de pouvoir revenir à moment antérieur de la session, avant d’avoir eu cette idée artistique géniale qui s’est avérée nulle et non avenue, avant d’avoir tenté un redécoupage des échantillons au microcoscope qui a finalement tué toute forme de musicalité, avant qu’un programme plante pour une raison inconnue des services de police…​

N’ayez crainte, revenir à un cliché ne vous empêchera pas de revenir là où vous en êtiez.

Pour faire revenir la session à un cliché, cliquez sur le bouton de marche arrière situé à droite du bouton Exécutable.

Sélectionnez le cliché vers lequel vous voulez revenir et cliquez sur Ok. Un nouveau cliché est pris, la session se ferme, le cliché voulu est rappelé et la session se ré-ouvre.

Il est également possible de faire revenir uniquement un client à un état précédent de la session en faisant un clique droit sur le client, puis Retourner à un état précédent.
Si vous le souhaitez vous pouvez éditer pour chaque client les fichiers ignorés par les clichés dans la fenêtre de propriétés du client.

Avec l’option Cliché automatique à la sauvegarde, un cliché est pris juste après chaque sauvegarde de la session, sauf s’il n’y a aucun changement depuis le cliché précédent. Pour prendre un cliché à un autre moment, cliquez sur l’icône de marche arrière à droite du bouton Exécutable et sur Prendre un cliché maintenant, celà présente l’avantage de pouvoir nommer le cliché et d’avoir ainsi un repère temporel plus parlant que la date et l’heure du cliché.

## Les scripts de session

Les scripts de session permettent de programmer des actions personnalisés à l’ouverture, à la sauvegarde et à la fermeture de la session. Ils sont notamment utilisés pour les sessions avec Mémoire de la configuration de JACK.
Des connaissances en script shell sont nécessaires pour éditer ces scripts, mais tout un chacun peut les utiliser.

Les scripts de session se trouvent dans un dossier `ray-scripts` situé soit dans un dossier de la session, soit dans un dossier parent.
Par exemple, pour une session étant dans:
`~/Ray Sessions/avec_script_de_foo/ma session`

le dossier des scripts de session peut-être
`~/Ray Sessions/avec_script_de_foo/ma session/ray-scripts`
`~/Ray Sessions/avec_script_de_foo/ray-scripts`
`~/Ray Sessions/ray-scripts`
`~/ray-scripts`

L’intérêt d’un tel comportement est de pouvoir scripter un ensemble de sessions sans avoir à y recopier les scripts, mais surtout de livrer une session non scriptée lorsqu’on la transfère à quelqu’un d’autre pour un travail collectif.
Seul le dossier de scripts le plus près de la session dans l’arborescence sera considéré. Ainsi, un dossier `ray-scripts` vide dans une session désactivera les scripts pour cette session.

Pour éditer les scripts, commencez par créer une session avec le modèle avec les scripts de base, il s’agit d’un modèle de session avec des scripts ne comprenant absolument aucune action particulière. Rendez-vous dans le dossier `ray-scripts` dans le dossier de la session, vous y trouverez les fichiers `load.sh`, `save.sh` et `close.sh`. Dans chacun de ces scripts, `ray_control run_step` correspond à l’action normale effectuée (selon le script: charger, sauvegarder ou fermer la session). Si un de ces trois scripts ne vous est d’aucune utilité, supprimez le, ce sera du temps gagné de ne pas passer par ce script.

Les fichiers scripts doivent impérativement être exécutables pour fonctionner.

Vous aurez probablement besoin de l’utilitaire en ligne de commande `ray_control` pour effectuer des actions en rapport avec tel ou tel client. tapez `ray_control --help` pour connaître toutes ses possibilités.

Le modèle de session à mémoire de configuration de JACK utilise les scripts de session, mais on peut aussi imaginer moult actions possibles selon vos besoins et vos envies, par exemple :

- définir un ordre bien précis de lancement des clients à l’ouverture de la session (un exemple est fourni dans le code source)

- faire une copie de sauvegarde de la session sur un disque dur externe à chaque fermeture

- envoyer un raccourci Ctrl+S aux fenêtres des clients non sauvegardables à la sauvegarde de la session (un exemple est fourni dans le code source)

- Allumer la lumière rouge à l’entrée du studio à l’ouverture, l’éteindre à la fermeture

- Lancer la machine à café à la fermeture de la session (exemple débile, allez donc appuyer sur le bouton de la cafetière, de toutes façons faudra changer le filtre !)

- Faire beaucoup, beaucoup, beaucoup d’erreurs qui feront planter votre session, soyez prudents évidemment !

## Mémoire de la configuration de JACK

Il est possible grâce aux scripts de session de rappeler automatiquement la configuration de JACK spécifique à une session avant de la charger. Ce comportement pourra rappeler à certains le fonctionnement des studios LADISH, en beaucoup mieux fait, du moins c’est ce qui est espéré.

### Dans quels cas l’utiliser

Celà peut s’avérer utile:

- Si vous avez besoin d’utiliser une interface audio spécifique pour la session

- Si vous travaillez sur de multiple projets avec des fréquences d’échantillonage différentes (telle session sur 44100 Hz, telle autre sur 48000 Hz).
  Ainsi celà vous évitera d’avoir à reconfigurer, arrêter et redémarrer JACK vous même, ou encore d’éviter d’oublier de le faire et de se faire insulter par certains programmes.

- Si vous voulez éviter de charger une session très gourmande en DSP (par exemple en phase de mixage) avec un tampon trop petit (128 par exemple).
  Notez que sur la plupart des interfaces audio, il est possible de changer la taille du tampon à chaud (sans redémarrer JACK).

### Utilisation

Il est nécessaire que l’option Scripts de session soit enclenchée (Cette option est enclenchée par défaut).

Pour utiliser le mémoire de configuration de JACK, créez une nouvelle session à partir du modèle Avec mémoire de la configuration de JACK.
Il s’agit en fait d’une session scriptée (voir Les scripts de session) qui lance un script fourni avec RaySession, mais qui lui est complètement externe, ainsi RaySession n’a toujours aucun rapport direct avec JACK.

Lisez la fenêtre d’informations à ce sujet puis validez. JACK redémarre puis votre session se lance.

### Principe de fonctionnement

À chaque fois que la session est sauvegardée, la configuration de JACK est sauvegardée dans la session, dans le fichier `jack_parameters`.
Avant l’ouverture de la session, JACK est redémarré si la configuration de la session est différente de la configuration actuelle de JACK.
Après la fermeture de la session, JACK est si nécessaire redémarré avec la configuration en cours avant l’ouverture.

La configuration des ponts PulseAudio → JACK est également sauvegardée et restaurée avec la configuration de JACK.

Si vous ouvrez cette session après l’avoir copiée sur un autre ordinateur, la configuration de JACK ne sera pas rappellée mais sera écrasée lors de la sauvegarde. Seule la fréquence d’échantillonage de la session sera utilisée.

### Cas particuliers

Pour ouvrir une session sans recharger sa configuration de JACK:

- désactivez l’option Scripts de session

- ouvrez la session

Pour changer la configuration de JACK d’une session:

- Démarrez JACK avec la configuration désirée

- Désactivez l’option Scripts de session

- Ouvrez la session

- Ré-activez l’option Scripts de session

- Sauvegardez la session

Pour rendre une ancienne session sensible à la configuration de JACK

- copiez le dossier `ray-scripts` d’une session avec mémoire de la configuration de JACK dans le dossier de la session

- Activez l’option Scripts de session

- Ouvrez la session

ou

- déplacez la session dans un sous-dossier contenant le dossier `ray-scripts` adhoc

- Ouvrez la session

## Sous le capot

RaySession n’est en réalité qu’une interface graphique pour ray-daemon. Lorsque vous lancez RaySession, l’interface graphique lance le démon et s’y connecte, et elle arrête le démon lorsqu’on la ferme. L’interface graphique et le démon communiquent entre eux par messages OSC (Open Sound Control), comme c’est le cas entre le démon et les clients NSM. Ainsi, vous pouvez connecter plusieurs interfaces graphiques à un démon, même à distance. Tapez `raysession --help` pour voir comment faire.

Il n’est pas interdit d’avoir plusieurs instances de démon lancés simultanément, ainsi si vous lancez RaySession alors qu’une instance est déjà lancée, celle-ci lancera un nouveau démon. Toutefois, cette façon de travailler étant peu commune, l’utilisation d’un seul démon est favorisée. Ainsi, si un démon tourne et qu’il n’a aucune interface graphique attachée, raysession se connectera à ce démon par défaut.

## Contrôler RaySession en ligne de commande

la commande `ray_control` vous permet de faire a peu près tout ce qu’il est possible de faire avec l’interface graphique, et même un peu plus. tapez `ray_control --help-all` pour connaître l’ensemble des possibilités.

Au cas où il y a plusieurs démons lancés (voir Sous le capot), `ray_control` ne considerera que celui qui a été lancé en premier, sauf si vous spécifiez son port OSC avec l’option `--port` ou la variable d’environnement RAY_CONTROL_PORT.

On pourrait penser qu’il n’y a pas d’intérêt à utiliser `ray_control` puisque la commande `oscsend` permet d’envoyer un message OSC au démon, c’est faux.
D’une part, parce que `oscsend` permet d’envoyer des messages mais pas d’obtenir des informations de manière simple (quels sont les clients actifs ? quel est l’executable de tel client ? …​), d’autre part parce que la commande `ray_control` se terminera lorsque l’action demandée sera effectuée, par exemple `ray_control open_session ma_session` se terminera lorsque la session sera chargée.

Pensez à affecter `ray_control save` à un raccourci global de votre environnement de bureau (Ctrl+Meta+S), celà vous fera gagner un temps fou !

## Foire aux questions

- Est-il toujours intéressant de lancer Ardour (ou un autre DAW compatible NSM) directement plutôt que dans RaySession ?

  Sauf pour un projet vraiment tout petit, Non.
  Si vous utilisez Ardour, lancez le toujours depuis RaySession, d’une part le cliché automatique à la sauvegarde peut vous être d’un secours inespéré, d’autre part, vous n’êtes pas à l’abri d’avoir besoin d’un autre programme même si vous ne l’aviez pas prévu.

- Puis-je lancer dans une session RaySession un projet Ardour déjà existant ?

  Vous trouverez dans le menu Fichier → Utilitaires → Convertir une session Ardour en session Ray, celà crée et lance une session RaySession à partir d’une session Ardour. Il n’est pas surfait de faire une copie de sauvegarde de votre session Ardour avant de lancer ce script. Bien évidemment, il ne faut pas que Ardour soit ouvert avec cette session pendant l’execution de ce script, mais ça vous l’aviez déjà compris.