# ShowFlo > Lanceur de cues libre et multiplateforme pour le spectacle vivant (OSC, MIDI, audio, vidéo, scripts, réseau). ### Une liste, une touche Le spectacle est une liste de cues. La touche Espace fait GO sur la cue de la playhead, qui passe ensuite à la suivante. ### Tous les protocoles d’une régie OSC avec fondus et courbes, MIDI et MIDI Show Control, fichiers MIDI, scripts Python, HTTP et WebSocket, son, vidéo. ### Piloté de l’extérieur Une console, un capteur ou un autre logiciel peut faire GO par OSC ou MIDI : ce sont les déclencheurs. ### Prêt pour les IA ShowFlo a son propre serveur MCP, et cette documentation existe aussi en Markdown pour les assistants. --- # Installer ShowFlo > Installer ShowFlo depuis les sources sous Linux, macOS ou Windows, et le lancer. ShowFlo s’installe pour l’instant depuis ses sources. Il faut **Python 3.12** ou plus récent. ## 1. Créer l’environnement Dans le dossier de ShowFlo : ```bash python3 -m venv .venv .venv/bin/pip install -e ".[dev,network,audio,video]" ``` Sous Windows : ```powershell python -m venv .venv .venv\Scripts\pip install -e ".[dev,network,audio,video]" ``` Les groupes entre crochets sont facultatifs : | Groupe | Ce qu’il ajoute | |---|---| | `audio` | la lecture de fichiers son (sounddevice, soundfile, soxr) | | `video` | les cues vidéo | | `network` | le serveur de contrôle HTTP et WebSocket, et le serveur MCP | | `dev` | les essais et l’analyse du code, pour qui développe ShowFlo | Sans `audio`, ShowFlo démarre quand même : le type de cue Audio n’est simplement pas proposé, et un projet qui en contient s’ouvre normalement. ## 2. Lancer ShowFlo ```bash ./showflo.sh # ShowFlo vide ./showflo.sh mon-show.sflo # ouvre un projet ``` Sous Windows, `scripts/windows/lancer_showflo_venv.bat` fait la même chose. Sous GNOME, `./install_launcher.sh` ajoute une icône sur le Bureau et dans Activités. ## 3. Et ensuite Lisez [Comprendre la liste de cues](/start/cue-list/) : c’est la seule notion à maîtriser avant de bâtir un premier spectacle. --- # Comprendre la liste de cues > La playhead, le GO, les comportements Unique, Continue et Auto-follow, et les groupes. Un spectacle, dans ShowFlo, est une **liste de cues**. Une cue est une action : envoyer un message OSC, jouer un son, lancer une vidéo, exécuter un script. Le projet s’enregistre dans un fichier `.sflo`. ## La playhead et le GO La **playhead** marque la prochaine cue à partir. La touche **Espace** fait **GO** : la cue de la playhead part, et la playhead passe à la suivante. Pendant le spectacle, la régie ne fait généralement que ça. On peut aussi lancer une cue précise sans déplacer la playhead, ou déplacer la playhead sans rien lancer. C’est utile en répétition, pour reprendre au milieu d’une scène. ## Les comportements Chaque cue a un **comportement**, qui dit ce qui se passe après elle. Un clic dans la colonne fait passer d’un comportement à l’autre. | Comportement | Ce qui se passe | |---|---| | **Unique** | La séquence s’arrête après cette cue. Il faudra un autre GO. | | **Continue** | La cue suivante part en même temps que celle-ci. | | **Auto-follow** | La cue suivante part quand celle-ci est terminée (après le post-délai). | Avec ces trois comportements, un seul GO peut déclencher toute une suite : un son qui part en même temps qu’un changement de lumière (Continue), puis un noir quand le son finit (Auto-follow). ## Les groupes Un **groupe** rassemble des cues sous une seule ligne. Il a un type : | Type | Ce qui se passe au GO | |---|---| | **Séquence** | les cues du groupe partent l’une après l’autre | | **Simultané** | toutes les cues du groupe partent en même temps | | **Aléatoire** | une seule cue du groupe, choisie au hasard | ## Les couleurs Une cue peut prendre une couleur (rouge, vert, bleu, jaune, mauve) pour se repérer dans une longue liste. Les teintes sont sombres exprès : en salle, l’écran de la régie ne doit pas éclairer. --- # Les types de cues > Ce que fait chaque type de cue de ShowFlo, de l’OSC à la vidéo. Chaque cue a un type, qui dit ce qu’elle fait au GO. Cette page en donne la vue d’ensemble ; chaque type aura bientôt sa page détaillée. ## OSC Envoie un message OSC (*Open Sound Control*) à une destination, en UDP ou en TCP. Une cue OSC peut faire un **fondu** d’une valeur vers une autre, avec une courbe au choix. C’est la cue de base pour piloter un logiciel de lumière, de vidéo ou de son. ## MIDI Envoie un message MIDI : note, contrôleur, changement de programme, ou commande **MIDI Show Control** (MSC) pour une console. ## Fichier MIDI Joue un fichier MIDI standard (`.mid`) vers un port MIDI. ## Script Exécute un script Python. Pour ce que les autres types ne font pas. ## Réseau Envoie une requête HTTP ou un message WebSocket. ## Playback Agit sur d’autres cues : les lancer, les arrêter, les mettre en pause, ou faire une **transition** (un fondu de l’état en cours vers un autre). ## Audio Fixe l’état de la **Scène audio** : quels sons jouent, à quel niveau, sur quels bus. ## Vidéo Diffuse une vidéo, une image ou une couleur sur une sortie vidéo. ## Boucle Enregistre une boucle en direct (par exemple au micro) puis la rejoue. La cue a deux actions : **Enregistrer** et **Fermer**. --- # Piloter ShowFlo de l’extérieur > Les déclencheurs, pour faire GO depuis une console, un capteur ou un autre logiciel, par OSC ou MIDI. Un projet ShowFlo peut **recevoir** des messages OSC et MIDI et y réagir : GO, STOP, PAUSE, saut de playhead, écriture d’une valeur dans une cue. Tout se règle dans **Réglages (Ctrl+,) → onglet DÉCLENCHEURS**, et s’enregistre dans le fichier `.sflo` du projet. ## 1. Activer une source | Source | Réglage | |---|---| | OSC entrant | case « Écouter » et un port UDP (8766 par défaut ; 9000 est souvent pris par MadMapper, Reaper ou TouchDesigner) | | MIDI entrant | case « Écouter » et un port d’entrée MIDI du projet | L’état s’affiche à droite : « à l’écoute », « arrêté », ou l’erreur (port déjà pris, appareil débranché). Les réglages sont **propres au projet** : ouvrir un autre projet arrête ses sources et démarre celles du nouveau. ## 2. Créer un déclencheur 1. Cliquez sur **Ajouter**. Une ligne apparaît : source OSC, action « GO (playhead) ». 2. Le plus simple : sélectionnez la ligne, cliquez sur **Apprendre**, puis appuyez sur le bouton de votre surface de contrôle, ou envoyez le message OSC. Le filtre se remplit tout seul. 3. Choisissez l’action et, si elle en demande une, la cue ou le groupe visé. 4. Au besoin, un **anti-rebond** en millisecondes : un bouton ou un capteur qui répète son message n’enverra qu’un GO par fenêtre de temps. Le moniteur « Dernier événement reçu » montre en tout temps ce que ShowFlo entend. ### Le filtre Il s’édite aussi à la main, par un double-clic dans la colonne Filtre. | Source | Syntaxe | Exemples | |---|---|---| | OSC | `/adresse [arguments…]`, avec les jokers `*` et `?` dans l’adresse | `/showflo/go`, `/pupitre/*`, `/cue 3` | | MIDI | `type [chN] [numéro]` ; une partie absente vaut n’importe quoi | `note_on ch1 60`, `control_change ch1 7`, `note_on` | Un `note_on` de vélocité 0 compte comme un `note_off` et ne déclenche rien. Un filtre vide n’attrape rien. ## 3. Les actions | Action | Effet | |---|---| | GO (playhead) | comme la touche Espace | | GO sur une cue | lance la cue visée sans toucher à la playhead | | STOP, PAUSE, REPRENDRE tout | comme les boutons de la barre d’outils | | PAUSE / REPRENDRE | une seule touche : pause si quelque chose joue, reprise si quelque chose est en pause | | STOP, PAUSE, REPRENDRE une cue | sur la cue visée seulement | | Playhead sur une cue | déplace la playhead sans rien lancer | | Écrire une valeur dans une cue | met la valeur reçue, remise à l’échelle, dans un champ de la cue visée | | Panique MIDI | coupe toutes les notes tenues sur les ports MIDI du projet | | Suivre le MSC reçu | une console MIDI Show Control pilote ShowFlo : GO 12 lance la cue numéro 12 | --- # ShowFlo et les IA > Brancher un assistant IA sur ShowFlo par MCP, et lire cette documentation en Markdown. ShowFlo est fait pour travailler avec un assistant IA : l’assistant peut lire le projet, ajouter des cues, faire GO et regarder le résultat. ## Brancher un assistant ShowFlo a son propre **serveur MCP** (*Model Context Protocol*). Il démarre avec ShowFlo et n’écoute que sur votre poste. 1. Ouvrez **Préférences → Réseau**. 2. Cliquez sur **Brancher un assistant** et choisissez Claude Desktop ou Claude Code. ShowFlo écrit lui-même la configuration de l’assistant (avec une copie de sauvegarde). Pour un autre assistant, « Autre » copie le bloc de configuration à coller. 3. Redémarrez l’assistant. Il n’y a aucun secret à copier : ShowFlo crée un jeton pour votre poste et le relais MCP le lit tout seul. En **mode spectacle**, l’assistant peut toujours lire et faire GO, mais pas modifier le projet. ## Cette documentation, pour les IA - [`/llms.txt`](/llms.txt) : la table des matières, pensée pour les modèles de langage. - [`/llms-full.txt`](/llms-full.txt) : toute la documentation en un seul fichier Markdown. - Chaque page existe aussi en Markdown : ajoutez `.md` à son adresse, par exemple [`/start/cue-list.md`](/start/cue-list.md). - [`/help.json`](/help.json) : les identifiants d’aide de ShowFlo et la page qui couvre chacun. --- # ShowFlo > A free, cross-platform cue launcher for live performance (OSC, MIDI, audio, video, scripts, network). ### One list, one key A show is a list of cues. The Space bar fires GO on the cue at the playhead, which then moves on to the next one. ### Every protocol a control booth needs OSC with fades and curves, MIDI and MIDI Show Control, MIDI files, Python scripts, HTTP and WebSocket, sound, video. ### Driven from outside A console, a sensor or another program can fire GO over OSC or MIDI: these are triggers. ### Ready for AI ShowFlo has its own MCP server, and this documentation is also available as Markdown for assistants. --- # Install ShowFlo > Install ShowFlo from source on Linux, macOS or Windows, and launch it. For now, ShowFlo is installed from source. You need **Python 3.12** or newer. ## 1. Create the environment In the ShowFlo folder: ```bash python3 -m venv .venv .venv/bin/pip install -e ".[dev,network,audio,video]" ``` On Windows: ```powershell python -m venv .venv .venv\Scripts\pip install -e ".[dev,network,audio,video]" ``` The groups in brackets are optional: | Group | What it adds | |---|---| | `audio` | sound file playback (sounddevice, soundfile, soxr) | | `video` | video cues | | `network` | the HTTP and WebSocket control server, and the MCP server | | `dev` | tests and code analysis, for ShowFlo developers | Without `audio`, ShowFlo still starts: the Audio cue type is simply not offered, and a project that contains audio cues opens normally. ## 2. Launch ShowFlo ```bash ./showflo.sh # empty ShowFlo ./showflo.sh my-show.sflo # open a project ``` On Windows, `scripts/windows/lancer_showflo_venv.bat` does the same. On GNOME, `./install_launcher.sh` adds an icon to the Desktop and to Activities. ## 3. What next Read [Understand the cue list](/en/start/cue-list/): it is the one idea to master before building a first show. :::note ShowFlo’s interface is in French for now. The English names of menus and buttons will follow the translated interface. ::: --- # Understand the cue list > The playhead, GO, the Unique, Continue and Auto-follow behaviours, and groups. In ShowFlo, a show is a **cue list**. A cue is an action: send an OSC message, play a sound, start a video, run a script. The project is saved in a `.sflo` file. ## The playhead and GO The **playhead** marks the next cue to fire. The **Space** bar fires **GO**: the cue at the playhead starts, and the playhead moves to the next one. During a show, that is usually all the operator does. You can also fire a specific cue without moving the playhead, or move the playhead without firing anything. This is handy in rehearsal, to pick up in the middle of a scene. ## Behaviours Each cue has a **behaviour**, which says what happens after it. Clicking in the column cycles through the behaviours. | Behaviour | What happens | |---|---| | **Unique** | The sequence stops after this cue. Another GO is needed. | | **Continue** | The next cue starts at the same time as this one. | | **Auto-follow** | The next cue starts when this one is finished (after its post-wait). | With these three behaviours, a single GO can run a whole sequence: a sound that starts together with a lighting change (Continue), then a blackout when the sound ends (Auto-follow). ## Groups A **group** gathers cues under a single line. It has a type: | Type | What happens on GO | |---|---| | **Sequence** | the cues in the group start one after the other | | **Simultaneous** | all the cues in the group start at the same time | | **Random** | a single cue from the group, picked at random | ## Colours A cue can take a colour (red, green, blue, yellow, purple) to find your way in a long list. The shades are dark on purpose: in the venue, the operator’s screen must not light up the room. --- # Cue types > What each ShowFlo cue type does, from OSC to video. Each cue has a type, which says what it does on GO. This page gives the overview; each type will soon have its own detailed page. ## OSC Sends an OSC (*Open Sound Control*) message to a destination, over UDP or TCP. An OSC cue can **fade** a value from one level to another, with a choice of curve. It is the basic cue for driving lighting, video or sound software. ## MIDI Sends a MIDI message: note, controller, program change, or a **MIDI Show Control** (MSC) command for a console. ## MIDI file Plays a standard MIDI file (`.mid`) to a MIDI port. ## Script Runs a Python script. For whatever the other types don’t do. ## Network Sends an HTTP request or a WebSocket message. ## Playback Acts on other cues: start them, stop them, pause them, or run a **transition** (a fade from the current state to another one). ## Audio Sets the state of the **Audio scene**: which sounds play, at what level, on which buses. ## Video Shows a video, an image or a colour on a video output. ## Loop Records a loop live (from a microphone, for instance) and plays it back. The cue has two actions: **Record** and **Close**. --- # Drive ShowFlo from outside > Triggers, to fire GO from a console, a sensor or another program, over OSC or MIDI. A ShowFlo project can **receive** OSC and MIDI messages and react to them: GO, STOP, PAUSE, playhead jumps, writing a value into a cue. Everything is set in **Settings (Ctrl+,) → TRIGGERS tab** (*Réglages → DÉCLENCHEURS* in the current French interface), and is saved in the project’s `.sflo` file. ## 1. Turn on a source | Source | Setting | |---|---| | Incoming OSC | “Listen” box and a UDP port (8766 by default; 9000 is often taken by MadMapper, Reaper or TouchDesigner) | | Incoming MIDI | “Listen” box and one of the project’s MIDI input ports | The status shows on the right: “listening”, “stopped”, or the error (port already in use, device unplugged). Settings belong to the **project**: opening another project stops its sources and starts the new one’s. ## 2. Create a trigger 1. Click **Add**. A line appears: OSC source, action “GO (playhead)”. 2. The easiest way: select the line, click **Learn**, then press the button on your control surface, or send the OSC message. The filter fills itself in. 3. Choose the action and, if it needs one, the target cue or group. 4. If needed, a **debounce** in milliseconds: a button or sensor that repeats its message will send only one GO per time window. The “Last event received” monitor always shows what ShowFlo hears. ### The filter It can also be edited by hand, with a double-click in the Filter column. | Source | Syntax | Examples | |---|---|---| | OSC | `/address [arguments…]`, with `*` and `?` wildcards in the address | `/showflo/go`, `/desk/*`, `/cue 3` | | MIDI | `type [chN] [number]`; a missing part matches anything | `note_on ch1 60`, `control_change ch1 7`, `note_on` | A `note_on` with velocity 0 counts as a `note_off` and fires nothing. An empty filter catches nothing. ## 3. Actions | Action | Effect | |---|---| | GO (playhead) | like the Space bar | | GO on a cue | fires the target cue without touching the playhead | | STOP, PAUSE, RESUME all | like the toolbar buttons | | PAUSE / RESUME | a single key: pause if something plays, resume if something is paused | | STOP, PAUSE, RESUME a cue | on the target cue only | | Playhead to a cue | moves the playhead without firing anything | | Write a value into a cue | puts the received value, rescaled, into a field of the target cue | | MIDI panic | silences every held note on the project’s MIDI ports | | Follow received MSC | a MIDI Show Control console drives ShowFlo: GO 12 fires cue number 12 | --- # ShowFlo and AI > Connect an AI assistant to ShowFlo over MCP, and read this documentation as Markdown. ShowFlo is built to work with an AI assistant: the assistant can read the project, add cues, fire GO and look at the result. ## Connect an assistant ShowFlo has its own **MCP server** (*Model Context Protocol*). It starts with ShowFlo and listens on your computer only. 1. Open **Preferences → Network**. 2. Click **Connect an assistant** and choose Claude Desktop or Claude Code. ShowFlo writes the assistant’s configuration itself (keeping a backup copy). For another assistant, “Other” copies the configuration block to paste. 3. Restart the assistant. There is no secret to copy: ShowFlo creates a token for your computer and the MCP relay reads it on its own. In **show mode**, the assistant can still read and fire GO, but cannot change the project. ## This documentation, for AI - [`/llms.txt`](/llms.txt): the table of contents, written for language models. - [`/llms-full.txt`](/llms-full.txt): the whole documentation in a single Markdown file. - Every page is also available as Markdown: add `.md` to its address, for example [`/en/start/cue-list.md`](/en/start/cue-list.md). - [`/help.json`](/help.json): ShowFlo’s help identifiers and the page that covers each one.