Tones

jambonz has a built in tone generate which can create either simple tones like a confirmatin beep or generate more complex patterns fpr things like ringing tone.

These. can be used in place of a URL in the play verb or in multiple other verbs that have a playback function; dial.dialMusic, dub.play config.onHoldMusic

Tone

Tone urls generate a simple single frequncy tone played for a given duration.

tone://?freq=<hz>&duration=<ms>&gainDb=<db>

Examples:

• tone:// — 440 Hz, plays until stopped
• tone://?freq=1000&duration=500 — 1 kHz for half a second
• tone://?freq=350&duration=2000&gainDb=-6 — 350 Hz, 2 sec, 6 dB quieter

Tone Stream

jambonz supports a common subset of the TGML format to generate more complex tones, these are most commonly used for things like ringing tone.

tone_stream://%(on_ms, off_ms, freq1[, freq2, …])

Tone elements — %(on_ms, off_ms, freq1[, freq2, …])

• on_ms / off_ms — tone and silence durations in milliseconds
• one or more frequencies, mixed (summed) when you list several — e.g. %(2000,4000,440,480)
• off_ms = 0 → a continuous (held) tone for the on duration

Sequences — multiple elements joined with ;, played in order as one period

• e.g. UK ring: %(400,200,400,450);%(400,2000,400,450)

Loop suffix — ;loops=N

• N times through the whole sequence; -1 = loop forever (until play.stop/replace)
• omitted = play once

Default variables (apply to %() elements that follow them)

• v=<dB> — volume, relative to the base level (−63…0 dB range)
• d=<ms> — default on-duration when an element leaves the on field blank
• w=<ms> — default off-duration when the off field is blank

Not supported (returns an error)

• Volume sweeps / ramps — >, <, + (e.g. the FS “BONG”)
• Prefix repeat counts — l= (per-tone) and L= (whole-script)
• Channel / sample-rate overrides — c=, r=
• File-based form — tone_stream://path=/path/to.tgml
• Frequency-notation operators — modulation ×, “either/or” //, sequence / (these are E.180 notation, not TGML input; the parser only takes plain numbers)

Anything unrecognized fails with unsupported tone_stream token "..." rather than silently degrading — so a typo or an unsupported form surfaces instead of playing the wrong thing.

International Tones

Jambonz includes aliases for the ring tone pattern in most countries, you can sepcify this using the tone_stream url format:

tone_stream://<country>.<tone>

Consult this tabled for the full list of supported countries, their urls and tone patterns

Notation & approximations

E.180 uses a compact frequency notation; these URLs translate it as follows:

• f1+f2 — simultaneous dual tone → both frequencies mixed in one %( ).
• f1×f2 — f1 modulated by f2 → modulation can’t be expressed in tone_stream, so the carrier f1 is used (e.g. Singapore 425×24 → 425 Hz).
• f1/f2 — f1 followed by f2 (sequence) → the first frequency is used (flagged in Notes).
• f1//f2 — some exchanges use f1, others f2 → the common dual-tone alternative is chosen where present (e.g. US 420×40//500×40//440+480 → 440+480), otherwise the first (flagged).
• Some entries list 25 Hz (the ringing current, inaudible as a tone) → substituted with 425 Hz audible ringback (flagged).
• Cadences map 1:1: 0.4 on 0.2 off 0.4 on 2.0 off → %(400,200,…);%(400,2000,…).

Caveats

• Generated from E.180 (2010); operators may have changed tones since. Verify anything critical.
• Where a country lists Ringing tone I/II/III variants, the first (primary) variant is used; the source column shows the ITU value.
• Puerto Rico has no ringing tone in E.180 (only a payphone tone); US-style 440+480 commonly applies.
• “Warble” tones (three simultaneous frequencies, e.g. Australia 400+425+450) are rendered as a plain mix — close, but not a true frequency sweep.