Kraftor SAM MIDI
Media
User Manual
Version 1.1
Kraftor SAM is a Software Automatic Mouth text-to-speech firmware for Kraftor / SAMD21 hardware. It reads typed text over USB Serial, stores phrases in RAM and optional RC256 FRAM, and lets you trigger stored phrases or shape the voice via USB MIDI or the hardware serial MIDI input.
Version History
- v1.1 (2026-05-03) : SAM text-to-speech with USB/serial MIDI control, RAM phrase slots, optional RC256 FRAM phrase storage, serial commands, and OLED status display support.
MIDI Channel Configuration
The firmware listens in MIDI omni mode. USB MIDI and Serial1 MIDI are both active at the same time and use the same note, control change, and pitch bend handlers.
| MIDI Input | Function | Channel |
|---|---|---|
| USB MIDI | Trigger sentence slots and control voice parameters | Omni |
| Serial MIDI | Trigger sentence slots and control voice parameters | Omni |
Sentence Banks
Kraftor SAM can store short sentences and trigger them from MIDI notes. RAM slots are always available. FRAM slots are available when an RC256 FRAM is detected on I2C address 0x50.
| Bank | Slots | MIDI Notes | Persistence |
|---|---|---|---|
| RAM | 20 slots, R0-R19 | 28-47 | Cleared on power-off or reset |
| FRAM | 100 slots, F0-F99 | 48-127 for F0-F79 | Saved in optional RC256 FRAM |
Each sentence can contain up to 200 characters. The FRAM stores 100 sentences, but MIDI can directly address the first 80 FRAM slots because MIDI notes stop at 127. The remaining FRAM slots are available through the serial commands.
MIDI Messages
Note On – Sentence Triggering
MIDI Note On messages trigger stored sentences. Velocity is not used for volume in this firmware version.
- Notes 28-47: play RAM slots R0-R19.
- Notes 48-127: play FRAM slots F0-F79 when RC256 FRAM is present.
- Other notes: ignored and reported as out of range on USB Serial and the OLED.
- Note Off: turns off the status LED only; spoken phrases play to completion.
| MIDI Note | Slot | Action |
|---|---|---|
| 28 | R0 | Play RAM sentence slot 0 |
| 29 | R1 | Play RAM sentence slot 1 |
| 47 | R19 | Play RAM sentence slot 19 |
| 48 | F0 | Play FRAM sentence slot 0 |
| 49 | F1 | Play FRAM sentence slot 1 |
| 127 | F79 | Play FRAM sentence slot 79 |
Pitch Bend – SAM Pitch Control
Pitch Bend controls the SAM pitch parameter. The full 14-bit MIDI pitch bend range is mapped to SAM values 255-0, so lower MIDI bend values produce higher SAM pitch values in the firmware mapping.
| Pitch Bend Value | SAM Pitch Value | Effect |
|---|---|---|
| -8192 | 255 | Highest mapped SAM pitch value |
| 0 | about 127 | Center pitch |
| +8191 | 0 | Lowest mapped SAM pitch value |
Default pitch is 64.
CC1 – Speed
MIDI CC1 controls SAM speech speed. MIDI values 0-127 are mapped to SAM speed values 255-1. Higher CC1 values make speech faster.
| CC1 Value | SAM Speed Value | Effect |
|---|---|---|
| 0 | 255 | Slowest mapped speech |
| 127 | 1 | Fastest mapped speech |
Default speed is 72.
CC2 – Mouth
MIDI CC2 controls the SAM mouth parameter. MIDI values 0-127 are mapped linearly to SAM values 0-255.
| CC2 Value | SAM Mouth Value |
|---|---|
| 0 | 0 |
| 127 | 255 |
Default mouth is 128.
CC3 – Throat
MIDI CC3 controls the SAM throat parameter. MIDI values 0-127 are mapped linearly to SAM values 0-255.
| CC3 Value | SAM Throat Value |
|---|---|
| 0 | 0 |
| 127 | 255 |
Default throat is 128.
Ignored MIDI Messages
- Control Change messages other than CC1, CC2, and CC3
- Note velocity
- Notes outside the RAM and FRAM trigger ranges
Serial Text And Commands
Open the USB Serial port at 115200 baud. Type a line of text and press Enter to speak it. Lines that start with ! are commands for managing the sentence banks.
| Command | Function | Example |
|---|---|---|
| !INFO? | Report RAM slots, FRAM status, MIDI note bases, max sentence length, and firmware version | !INFO? |
| !GET | Read one sentence slot | !GET R 0 |
| !SET | Store text in one sentence slot | !SET F 12 hello from SAM |
| !ERASE | Clear one sentence slot | !ERASE R 3 |
| !PLAY | Speak one sentence slot | !PLAY F 25 |
| !DUMP | List all sentences in a bank | !DUMP R |
Use R for RAM slots and F for FRAM slots. FRAM commands return !ERR nofram when no RC256 FRAM is detected.
Quick Reference Table
| Message | Function | Range |
|---|---|---|
| Note On | Trigger RAM sentence slots | Notes 28-47, slots R0-R19 |
| Note On | Trigger FRAM sentence slots | Notes 48-127, slots F0-F79 |
| Pitch Bend | SAM pitch | -8192 to +8191, mapped to 255-0 |
| CC1 | SAM speed | 0-127, higher is faster |
| CC2 | SAM mouth | 0-127 mapped to 0-255 |
| CC3 | SAM throat | 0-127 mapped to 0-255 |
| USB Serial | Speak typed text or manage sentence banks | 115200 baud |
Connections
The Kraftor SAM firmware accepts control from:
- USB Serial for typed speech and sentence bank commands
- USB MIDI for notes, control changes, and pitch bend
- Serial MIDI on the hardware serial MIDI input
Audio is output from the SAMD21 DAC on A0.
OLED Display
If an OLED display is detected at I2C address 0x3C, it shows:
- SAM MIDI on startup
- The firmware version
- The last MIDI note and sentence slot
- The spoken text or empty/error status for the selected slot
Optional FRAM
If an RC256 FRAM is detected at I2C address 0x50, the firmware enables persistent sentence slots. On first use, a missing FRAM header is initialized automatically.
Tools
The best way to use Kraftor SAM is with the companion SAM Designer tool:
https://deladriere.github.io/SAM_Designer/
SAM Designer runs in the browser and provides a dedicated interface for typing text, sending it to Kraftor SAM, saving and recalling sentence slots, and controlling voice parameters. Use a Chromium-based browser for Web Serial and Web MIDI support.
You can also use any USB Serial terminal at 115200 baud to type text, save phrases, dump sentence banks, and trigger stored sentences. Use a USB MIDI or DIN MIDI controller to play sentence slots and control pitch, speed, mouth, and throat.
Firmware
Do not use this firmware for Emy, Emy Terminal.
How to install the firmware on Kraftor
