Web Beep Specification

Status

Latest Draft 2012-01-01

First Draft 2011-12-04

1. Introduction

This document defines an algorithm for encoding short sequences of arbitrary text as quasi-musical audio data.

The input will be a Unicode text string, the output a signal expressed as an array of numeric values.

The algorithm was developed as part of the Web Beep service and is provided here to facilitate development of, and interoperability with, related services and applications.

See Also

2. Terminology

An open source Reference Implementation is available and relevant sections of its documentation are linked from here with links labeled [RI].

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Everything in this specification is normative unless otherwise stated.

3. Encoding Algorithm

The algorithm has three distinct stages:

3.1 Block Diagram

Informative

encoding

3.2 Text Preprocessing

The input of the Web Beep algorithm is a Unicode text string. Preprocessing of that string involves converting it to an ASCII representation and generating and prepending a checksum character. The string resulting from this preprocessing is passed to the next stage, Character Mapping.

ToASCII

The Unicode characters in the source string are initially encoded in ASCII using the full (no-flags) algorithm as described in java.net.IDN.toASCII, summarised as follows :

Internationalized domain names are defined in RFC 3490. RFC 3490 defines two operations: ToASCII and ToUnicode. These 2 operations employ Nameprep algorithm, which is a profile of Stringprep, and Punycode algorithm to convert domain name string back and forth.

...

A label is an individual part of a domain name. The original ToASCII operation, as defined in RFC 3490, only operates on a single label. This method can handle both label and entire domain name, by assuming that labels in a domain name are always separated by dots. The following characters are recognized as dots: \u002E (full stop), \u3002 (ideographic full stop), \uFF0E (fullwidth full stop), and \uFF61 (halfwidth ideographic full stop). if dots are used as label separators, this method also changes all of them to \u002E (full stop) in output translated string.

The clauses above (and RFC 3490) are used normatively in Web Beep, with the exception that the Unicode input string is subject to the following condition:

Where encoding of a sequence longer than 63 characters is required, it is RECOMMENDED that it is created from a sequence of shorter sequences as defined here, although no algorithm is provided here for such multiple encodings.

Checksum

The checksum character to prepend to the ASCII representation is determined as followed:

  1. the numeric code value of each character (0-127) in the ASCII representation is obtained
  2. all numeric values are summed
  3. the lower 7 bits of the sum is the numeric value of the checksum character

Example

Informative

If the ASCII input string is "abc" :

So the resultant string with checksum is "&abc".

See Also

3.3 Character Mapping

The Character Mapping stage of the algorithm takes the string produced by Text Preprocessing and for each character in turn looks up entries in the mapping tables which will determine the required tones.

The numeric value of each 7-bit ASCII character is split into two values corresponding to the most significant 3 bits and lower 4 bits.

These values are used as indexes in the tables below to yield two frequency values each with a corresponding "Beats" value which give the duration of the tone (in duration units, multiples of 48.6111... milliseconds).

The mapping tables are as follows :

Most Significant Bits

Index Note Freq Beats
0 C 261.63 1
1 D 293.66 1
2 E 329.63 1
3 G 392 1
4 A 440 1
5 C 261.63 2
6 D 293.66 2
7 G 392 2

Least Significant Bits
Index Note Freq Beats
0 c 523.25 1
1 d 587.33 1
2 e 659.26 1
3 g 783.99 1
4 a 880 1
5 c 523.25 2
6 d 587.33 2
7 e 659.26 2
8 g 783.99 2
9 a 880 2
10 c' 1046.5 1
11 d' 1174.66 1
12 e' 1318.51 1
13 g' 1567.98 1
14 a' 1760 1
15 g' 1567.98 2

The frequency values are given here with an accuracy of two decimal places. No specific accuracy is REQUIRED, though implementations SHOULD use an appropriate approximation of values from the Western equally tempered scale with A = 440Hz.

The "Note"columns are informative, the ABC notation for the note corresponding to the frequency

Informative : the frequencies occur in a "black key" pentatonic scale, concert pitch

The results of these mappings will be the tuples:

are passed on to 3.3 Tone Generation

Example

Informative

Starting from the previous example, the input to this stage will be "&abc". Looking these characters up in the tables yields the following:

& ASCII hex 26

Low index=2, beats=1, freq=329.63

High index=6, beats=2, freq=587.33

a ASCII hex 61

Low index=6, beats=2, freq=293.66

High index=1, beats=1, freq=587.33

b ASCII hex 62

Low index=6, beats=2, freq=293.66

High index=2, beats=1, freq=659.26

c ASCII hex 63

Low index=6, beats=2, freq=293.66

High index=3, beats=1, freq=783.99

Hence the values passed forward will be the sequence :

3.4 Tone Generation

The values found via 3.2 Character Mapping will be used to set parameters in the Tone Generation stage of the algorithm.

Duration

The duration of individual tones SHOULD be toneDuration= 48.6111... ( = 140 / (60 * 48)) milliseconds.

Informative : listening tests suggested an approximate value for this, the exact value chosen so Beeps could be in sync with music at 140bpm in 3/4 or 4/4 time.

Generation

Start with an empty waveform, then:

for each set of values noteLow = (frequencyL, beatsL), noteHigh = (frequencyH, beatsH)

The waveform SHOULD then be padded by silence at least of toneDuration at the start and end.

Example

abc tone

Exchange Format

The numeric data resulting from the operations above will typically be rendered in an audio binary format and subsequently rendered through a media player. The choice of audio format is left to the implementor (the Reference Implementation internally generates .wav 16 bit PCM format mono, 22.05kHz, which is converted to mp3 externally using LAME see Constants.java, ToMP3.java and WavCodec.java)

4 Decoding

This section is informative.

// TODO, see How It Works of Web Beep

5 Reference Implementation

A reference implementation of this algorithm is available as part of the Web Beep application : source repository (also includes this documentation).

6 Notes

6.1 Idents

There may be a need for Web Beep signals to contain an identifying block or "Ident". In a particularly noisy environment, the robustness of Web Beep communications could be significantly improved by the use of an marker signal to indicate the start of a transmission. Additionally, in broadcast communications it's often desirable for the originator of the message to identify themselves, for example radio station Channel Ids or WiFi SSIDs. Neither of these scenarios are covered by Web Beep at present, however both are potentially supported by using the current algorithm over multiple messages. For example, a marker and/or broadcaster ID could be formed by sending a short string (e.g. "WB") a fixed time before the message proper.