Skip to main content

Introduction

TwitchMIDI is a full-featured configurable Twitch bot to connect with your MIDI equipment while streaming. Allow your viewers to be part of your musical creations!

Twitch MIDI Demo

🌟 If you want more... TwitchMIDI+ provides extensive documentation, extra features and a useful control panel, check out https://store.rafaelpernil.com/l/twitchmidiplus

Download​

Latest release - TwitchMIDI for Windows, Linux & MacOS (x86-64)

Installation​

  • Extract the zip
  • Run TwitchMIDI-yourplatform (e.g TwitchMIDI-win.exe)
  • Follow the configuration steps to link this bot to your account. You will see something like this:

  • Done. Have fun!

Note: For MacOS, open a terminal, "cd" into the extracted folder and then execute it from there with "./TwitchMIDI-macos". Otherwise you will get an error like: "no such file or directory, open './config/aliases.json'"

Using Node.js​

If you want to use this app with your installation of Node.js, feel free to do it.

Tested with Node.js 20 LTS and 22 LTS

  • Clone this project or download it
  • Run npm install
  • Run npm run build
  • And finally to execute run npm run start

Update​

Just put the new version in your folder. TwitchMIDI will configure everything automatically and add anything missing.

Why?​

This project was born out of an idea for my music streams (twitch.tv/rafaelpernil) where I play piano and improvise with my synth and drum machine. It is really fun, but I wanted to apply my software engineering skills to make something special for my streams, to provide my viewers a new fun way of interacting with my gear.

I had this idea for months but it was not up until recently that I started to define tangible goals and implement them. My previous project, PolyVolcaWeb using the Web MIDI API gave me the confidence and clarity to start :)

My goals were:

  • Create a Twitch bot and process commands
  • Create a set of MIDI functionalities such as MIDI clock with tempo adjustments, synced chord progressions, notes, loops, cc messages, macros...
  • Unite commands and MIDI functionalities
  • Make it fast, suitable for streamers, stable and easy to use

So far, this first version does all that, keep reading the features for more details!

Features​

  • Wide set of MIDI functionalities:
    • High precision MIDI Clock using "nanotimer" with adjustable tempo via !settempo
    • Sequencer on 4/4 time signature with infinite subdivisions (1 = Quarter note, 0.5 = 8th note, 0.25 = 16th note...)
    • Trigger individual notes, build a chord or send a melody separated by commas via !sendnote
    • Trigger looped chord progressions with specific length per chord via !sendloop with an extensive list of chords to choose from. See CHORDS.md
    • Remove your last request if you change your mind via !wrongloop
    • Support for music rests using "rest" as a replacement for a chord or note in !sendnote and !sendloop requests
    • Support for multiple time signatures per request using "[X/Y]" !sendloop requests (e.g "[4/4] Dmin7 G7 C" or "[5/4] Dmin7(2) G7(3) [4/4] Dmaj7(2) Dbm7(2) Cmaj7(2) Bm7(2)")
    • See the current chord progression via !midicurrentrequest
    • Check the chord progression request queue via !midirequestqueue
    • Change MIDI velocity via !midivolume
    • Send CC (Control Change) messages and sweeps between values via !sendcc
    • Clock-Loop synchronizer to correct sync issues via !syncmidi
    • Automatic synchronization that forces loops to wait until the start of the beat
    • On/Off bot toggle with !midion/!midioff
    • Pause requests with !midipause and resume with !midiresume
    • Ban users with !midibanuser and unban with !midiunbanuser
    • Set timeout between requests per user with !miditimeout
  • Configurable aliases on config/aliases.json
    • Commands - Add as many command aliases as you want
    • Macros - Launch a set of actions from a single command
    • Chord progressions/loops - Add an alias for a chord progresion to play or loop using "name/chords" syntax
    • Control Change controller names - Put a name to your Control Change controllers (e.g sustain: 64)
    • Control Change commands - Assign a set of cc commands
      • Sweep functionality, specify two values and the time in milliseconds to get from one value to other (e.g "cutoff 20(5000),cutoff 120(10000)")
      • List all added Control Change commands with their name via !cclist
    • Reload config/aliases.json, config/permissions.json and config/rewards.json file while using the bot with !fetchdb
  • Commands explanation with examples via !midihelp commandname
  • Fine-grained command access control with role check, whitelist and blackist on config/permissions.json
  • Channel Points reward mode enabled via REWARDS_MODE flag and configurable on config/rewards.json
    • Set the name of your channel points reward, the command to launch and the price (e.g. "Twitch Midi - Loop": ["!sendloop",100] )
    • Automatic enable/disable rewards on !midion/!midioff
    • Automatic points refund on bad requests / any kind of error
    • Commands only work for the streamer and mods
    • Allow VIPs to bypass rewards via VIP_REWARDS_MODE
  • Bundle optimized for different operating systems and no extra software required for execution
  • HTTP API to interact with the bot behind the scenes with an alternative UI (like TwitchMIDI+ Control Panel)
  • Internationalization with full support for English and Spanish as of right now
  • Update checking on startup, a message appears if there is a new version available
  • Automatic checking and fix of configuration files. It ensures that all settings are correct while keeping the good ones

Commands​

!midihelp​

    Shows all commands available and info about each command.

    Syntax:

        command // (e.g "sendloop")

!midion​

    Turns on the MIDI functionality of the bot

!midioff​

    Turns off the MIDI functionality of the bot

!midipause​

    Pauses the requests but keeps playing whatever was already playing

!midiresume​

    Reactivates requests after they were paused with !midipause

!addchord​

    Adds a chord progression or loop with an alias to config/aliases.json.

    Syntax:

        name/chords(chord length in quarter notes) // (e.g. "pop/C G(2) Amin(2) F")

!removechord​

    Removes a chord progression or loop with an alias from config/aliases.json.

    Syntax:

        alias // (e.g. "pop")

!chordlist​

    Shows all saved chord progressions or loops from config/aliases.json that can be used

!sendnote​

    Sends a note or a set of notes.

    Syntax:

        note1 note2 ... // (e.g. "C4 E4 G4")

!sendloop​

    Sends a loop with an alias or with chords.

    Syntax:

        chord1 chord2(chord length in quarter notes)... // (e.g. "C G Amin F","pop")

!wrongloop​

    Removes your last request from the queue

!sendcc​

    Sends a MIDI CC message with an alias, code or value sweeps.

    Syntax:

        controller value,controller2 value2(delay_in_ms) // (e.g. "43 100,43 60", "cutoff sweep", "cutoff 100,cutoff 10(10000)")

!midicurrentrequest​

    Shows the current request being played.

!midirequestqueue​

    Shows the request queue for chord progressions and loops.

!cclist​

    Shows a list of available CC command macros from config/aliases.json

!midivolume​

    Sets the velocity for the chords/notes/loops.

    Syntax:

        value between 0 and 100 // (e.g. "50","100")

!stoploop​

    Stops the loop once it ends

!fullstopmidi​

    Stops all MIDI messages and sound

!settempo​

    Starts the MIDI clock and sets a tempo.

    Syntax:

        tempo // (e.g. "120", "200")

!syncmidi​

    Restarts the MIDI clock and syncs loop and clock on the next repetition

!fetchdb​

    Refreshes aliases, rewards and permissions configurations from the respective files.

!midibanuser​

    Blocks access to TwitchMIDI commands and rewards to a given username.

    Syntax:

        !midibanuser username

!midiunbanuser​

    Unblocks access to TwitchMIDI commands and rewards to a previously blocked user.

    Syntax:

        !midiunbanuser username

!miditimeout​

    Sets a request timeout per user.

    Syntax:

        !miditimeout timeinseconds // (e.g. 20)

Troubleshooting​

Question: I get authentication errors each time I open the app. What can I do?

Answer:

Delete bot-tokens.json and broadcaster-tokens.json from your config folder. If that does not work, remove BROADCASTER_REFRESH_TOKEN, BROADCASTER_ACCESS_TOKEN, BOT_REFRESH_TOKEN and BOT_ACCESS_TOKEN from your .env file and re-configure it again

Question: My Twitch channel points rewards do not load correctly. What is happening?

Answer:

If you changed your client ID or updated from an old version, rewards may not load. To fix that, go to Channel Points, click on "Manage Rewards", scroll to the bottom and remove all TwitchMIDI rewards (they start by default with MIDI - something) Twitch Channel Point Rewards

Question: The app says there is an instance of TwitchMIDI already running but it is not open

Answer:

There is a .lock file generated when launching TwitchMIDI that is removed when it gets closed, even with runtime errors or exceptions. Unfortunately, the file will not be removed if you shutdown Windows with TwitchMIDI open. First make sure no instance of TwitchMIDI is running. If that is the case, just delete the .lock file.

Chords​

This program uses harmonics by scribbletune to convert chord notation to MIDI notes.

But, in addition to those provided by harmonics, I included some extra ones for a more confortable syntax.

See CHORDS.md for a full list