A tiny music format
with a long afterlife.

What RTTTL is

Ring Tone Text Transfer Language is a compact, plain-text description of one melodic line. A ringtone contains a name, three useful defaults and a comma-separated series of notes or rests. It contains no sampled audio, chords, lyrics or instruments. That deliberate simplicity makes it easy to store in flash memory, send through an API, inspect by eye and implement on a small processor.

RTTTL grew around Nokia's monophonic ringtone ecosystem. The surviving 1998 text grammar credits John Mostelo; a 1999 revision says it was aligned with Nokia Smart Messaging 2.0. Nokia handsets used closely related Composer and Smart Messaging note commands, but a textual .rtttl file and a binary over-the-air Smart Message are not the same transport format.

Anatomy of a string

The defaults section may contain the settings in any order. For maximum interoperability, include all three explicitly and keep the entire ringtone on one line.

Notes, rests and exact timing

A note token follows [duration][pitch][#][octave][.]. Pitch names are c d e f g a b; add # for a sharp and use p for a pause. A leading duration is a denominator, not milliseconds. A trailing dot makes a note 1.5 times as long.

The classic-safe subset

• Durations: 1, 2, 4, 8, 16, 32, optionally dotted.
• Pitches: natural notes and sharps only; flats must be rewritten enharmonically, such as B♭ → A♯.
• Octaves: target 4–7 unless the exact device documentation says otherwise.
• Name: no colon; keep it to 10 simple ASCII characters for vintage compatibility.
• Melody: one note at a time. Simultaneous MIDI notes must be reduced before conversion.

Duration formula

At tempo b, one quarter note lasts 60,000 / b milliseconds. A token with denominator d lasts (60,000 / b) × (4 / d); multiply by 1.5 when dotted. At 120 BPM, 8c lasts 250 ms and 8c. lasts 375 ms.

Where RTTTL really works

Support is not one binary yes/no. Use the support class and transfer path below before choosing an export profile.

Who RTTTL is useful for now

Phone deployment workflows

Classic Nokia: Composer or OTA, not a guessed file copy

1. Identify the exact model and manual.Look for Composer, “receiving a ringing tone,” Smart Messaging, OTA or infrared. Absence from the manual is a reason to stop and verify.
2. Prepare a conservative melody.Use a ≤10-character name, octaves 4–7, durations through 32, moderate tempo and a short note count.
3. Choose the documented route.For Composer, use the phone’s keypad controls for note, duration, octave, sharp and rest. For OTA/IR, use a tool that explicitly produces Nokia Smart Messaging ringing-tone data.
4. Test before distributing.Confirm pitch range, tempo, truncation and the number of custom-tone slots on the physical phone.

innovaphone: verify firmware, then import

1. Match the model.The manufacturer’s V7–V10 matrix names IP110, IP200, IP230, IP240, IP240-1000, IP241, IP222 and IP232.
2. Match the firmware.For V11 and later, consult the exact release notes or current model documentation because the historical matrix is no longer maintained.
3. Export a portable RTTTL file.Start with the classic-safe subset and one melody per file. Keep a MIDI conversion available as the documented alternative.
4. Import through the phone’s documented ringtone configuration.Web-interface paths differ across firmware. Select the imported tone, place a test call and confirm volume and looping behavior.

Hak5 WiFi Pineapple Pager

1. Create one .rtttl file per tone.The file contains one complete RTTTL string.
2. Copy it to /root/ringtones.Hak5 documents scp, sftp or editing directly on the device.
3. Test it from the shell.Run RINGTONE filename, or pass a complete quoted RTTTL string to RINGTONE.

Arduino tutorial: passive piezo + PlayRtttl

This route stores the melody in program flash and uses Arduino’s tone() facility to generate a square wave. The PlayRtttl project provides blocking and non-blocking APIs and currently tests examples on Arduino AVR boards, ESP8266, ESP32 and STM32.

1. Parts and wiring

• An Arduino-compatible board.
• A passive piezo transducer. An active buzzer with its own oscillator cannot reproduce arbitrary pitches.
• A current-limiting/driver circuit appropriate to the transducer and board. Never connect a low-impedance loudspeaker directly to a GPIO; follow the component datasheet and board current limits.
• For the example, connect the signal path to digital pin 11 and the return to ground. Change TONE_PIN when using another supported pin.

2. Install and play once

1. Install the library.Arduino IDE → Library Manager → search for PlayRtttl → Install.
2. Create a new sketch.Paste the example below and select the correct board and port.
3. Upload and listen.The blocking function plays the complete melody during setup().

#include <PlayRtttl.h>

constexpr uint8_t TONE_PIN = 11;
const char melody[] PROGMEM =
  "Signal:d=8,o=5,b=132:c,e,g,c6,4p,g,e,2c";

void setup() {
  playRtttlBlockingPGM(TONE_PIN, melody);
}

void loop() {
}

3. Keep buttons, sensors and networking responsive

For an interactive product, start playback once and call updatePlayRtttl() on every loop. Avoid long delay() calls because the player and your other tasks share the loop.

#include <PlayRtttl.h>

constexpr uint8_t TONE_PIN = 11;
const char melody[] PROGMEM =
  "Ready:d=16,o=5,b=140:c,e,g,8c6";

void setup() {
  startPlayRtttlPGM(TONE_PIN, melody);
}

void loop() {
  updatePlayRtttl();

  // Read buttons, update sensors, service networking, etc.
  // Call stopPlayRtttl() when an event should cancel the tone.
}

Troubleshooting

Alternative Arduino libraries

AnyRtttl provides blocking and non-blocking modes, custom timing/tone callbacks and PROGMEM support. NonBlockingRTTTL focuses on keeping I/O responsive. TinyRTTTL is a compact tone()-based class documented for Uno, ESP8266 and ATtiny85. Choose based on board support, timer use, maintenance and license—not only API size.

ESPHome + Home Assistant tutorial

ESPHome’s RTTTL component can drive a passive buzzer from ESP8266 software PWM or ESP32 LEDC, and it can alternatively render through an ESPHome speaker component. The RTTTL string is templatable, so Home Assistant can send a melody at runtime.

ESP32 example

1. Wire a passive buzzer safely.The example uses GPIO25. Use the correct driver circuit and a pin suitable for your board.
2. Add the output and RTTTL component.gain controls the component output level; actual loudness also depends on the hardware.
3. Expose an API action.Home Assistant can then supply any validated RTTTL string as song.

esphome:
  name: hallway_chime

esp32:
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

output:
  - platform: ledc
    pin: GPIO25
    id: buzzer_output

rtttl:
  output: buzzer_output
  id: rtttl_player
  gain: 60%
  on_finished_playback:
    - logger.log: "RTTTL playback finished"

api:
  actions:
    - action: play_rtttl
      variables:
        song: string
      then:
        - rtttl.stop
        - rtttl.play:
            rtttl: !lambda 'return song;'

After the node is connected to Home Assistant, open Developer Tools → Actions and select the generated ESPHome action for hallway_chime. Supply, for example:

song: "Door:d=8,o=5,b=140:c,e,g,4c6"

Practical smart-home mappings

Ready-made examples make the audience broader than DIY boards: the ESPHome device repository documents Apollo temperature, plant and PoE multisensors with RTTTL-capable buzzers, while M5Stack publishes an ESPHome/Home Assistant RTTTL setup for the M5Dial’s onboard buzzer.

Tasmota: optional I²S RTTTL

Tasmota documents I2SRtttl for ESP32 audio builds. This is an advanced path: compile firmware with USE_I2S_AUDIO and USE_I2S_RTTTL, configure the I²S output, then issue a console, HTTP or MQTT-backed command such as:

I2SRtttl Signal:d=8,o=5,b=132:c,e,g,c6,4p,g,e,2c

The ordinary Tasmota Buzzer command is a beep/silence pattern with a bitmask; it is not the same as RTTTL. Use I2SRtttl only when the audio build and RTTTL option are present.

PICAXE: convert at development time

1. Open PICAXE Tune Wizard.In Programming Editor, choose PICAXE → Wizard → Tune Wizard.
2. Paste or import RTTTL.Use Edit → Paste Ringtone for copied text or File → Import Ringtone for a saved file.
3. Preview and generate.Test the monophonic tune, optionally select flashing outputs, then insert the generated tune command into the BASIC program.

Ways to implement RTTTL

Minimal parser algorithm

1. Split exactly twice on :.Validate a non-empty name, defaults section and notes section.
2. Parse defaults.Accept d, o and b; reject duplicates and out-of-range integers.
3. Tokenize notes on commas.For each token, read optional duration, pitch/rest, optional sharp, optional octave and optional dot.
4. Resolve timing and pitch.Apply defaults, calculate duration, then convert pitch and octave to frequency or MIDI note number.
5. Schedule sequentially.A rest advances time without sounding. Never overlap notes in a strict RTTTL renderer.
6. Return warnings separately.A long name or wide octave may be valid for a modern parser but unsafe for vintage hardware.

Production checklist

• Bound input length and maximum note count.
• Normalize whitespace and letter case.
• Reject malformed tokens with a position.
• Cap total playback time and frequency range.
• Stop a current melody before replacing it.
• Keep playback non-blocking where other I/O matters.
• Separate classic warnings from syntax errors.
• Preserve the original alongside normalized output.
• Test rests, dots, sharps and default overrides.
• Document timer, pin and amplifier constraints.

Primary documentation and libraries

Links are grouped by what they prove. Historical manuals may be hosted by archival manual sites, but the referenced content is the original manufacturer documentation.

Format and history

Phones and direct devices

Embedded and smart home