README
¶
Mnemonicode
Mnemonicode is a method for encoding binary data into a sequence of words which can be spoken over the phone, for example, and converted back to data on the other side.
Online package documentation is available via pkg.go.dev
To install the package:
go get hg.sr.ht/~dchapes/mnemonicode
or the command line programs:
go get hg.sr.ht/~dchapes/mnemonicode/cmd/...
or go build any Go code that imports it:
import "hg.sr.ht/~dchapes/mnemonicode"
For more information see https://github.com/singpolyma/mnemonicode or http://web.archive.org/web/20101031205747/http://www.tothink.com/mnemonic/
From the README there:
There are some other somewhat similar systems that seem less satisfactory:
-
OTP was designed for easy typing, and for minimizing length, but as a consequence the word list contains words that are similar ("AD" and "ADD") that are poor for dictating over the phone
-
PGPfone has optimized "maximum phonetic distance" between words, which resolves the above problem but has some other drawbacks:
-
Low efficiency, as it encodes a little less than 1 bit per character;
-
Word quality issues, as some words are somewhat obscure to non-native speakers of English, or are awkward to use or type.
-
Mnemonic tries to do better by being more selective about its word list. Its criteria are thus:
Mandatory Criteria:
-
The wordlist contains 1626 words.
-
All words are between 4 and 7 letters long.
-
No word in the list is a prefix of another word (e.g. visit, visitor).
-
Five letter prefixes of words are sufficient to be unique.
Less Strict Criteria:
-
The words should be usable by people all over the world. The list is far from perfect in that respect. It is heavily biased towards western culture and English in particular. The international vocabulary is simply not big enough. One can argue that even words like "hotel" or "radio" are not truly international. You will find many English words in the list but I have tried to limit them to words that are part of a beginner's vocabulary or words that have close relatives in other european languages. In some cases a word has a different meaning in another language or is pronounced very differently but for the purpose of the encoding it is still ok - I assume that when the encoding is used for spoken communication both sides speak the same language.
-
The words should have more than one syllable. This makes them easier to recognize when spoken, especially over a phone line. Again, you will find many exceptions. For one syllable words I have tried to use words with 3 or more consonants or words with diphthongs, making for a longer and more distinct pronounciation. As a result of this requirement the average word length has increased. I do not consider this to be a problem since my goal in limiting the word length was not to reduce the average length of encoded data but to limit the maximum length to fit in fixed-size fields or a terminal line width.
-
No two words on the list should sound too much alike. Soundalikes such as "sweet" and "suite" are ruled out. One of the two is chosen and the other should be accepted by the decoder's soundalike matching code or using explicit aliases for some words.
-
No offensive words. The rule was to avoid words that I would not like to be printed on my business card. I have extended this to words that by themselves are not offensive but are too likely to create combinations that someone may find embarrassing or offensive. This includes words dealing with religion such as "church" or "jewish" and some words with negative meanings like "problem" or "fiasco". I am sure that a creative mind (or a random number generator) can find plenty of embarrasing or offensive word combinations using only words in the list but I have tried to avoid the more obvious ones. One of my tools for this was simply a generator of random word combinations - the problematic ones stick out like a sore thumb.
-
Avoid words with tricky spelling or pronounciation. Even if the receiver of the message can probably spell the word close enough for the soundalike matcher to recognize it correctly I prefer avoiding such words. I believe this will help users feel more comfortable using the system, increase the level of confidence and decrease the overall error rate. Most words in the list can be spelled more or less correctly from hearing, even without knowing the word.
-
The word should feel right for the job. I know, this one is very subjective but some words would meet all the criteria and still not feel right for the purpose of mnemonic encoding. The word should feel like one of the words in the radio phonetic alphabets (alpha, bravo, charlie, delta etc).
Documentation
¶
Overview ¶
Package mnemonicode …
Index ¶
- Constants
- func DecodeWordList(dst []byte, src []string) (result []byte, err error)
- func EncodeWordList(dst []string, src []byte) (result []string)
- func NewDecodeTransformer() transform.Transformer
- func NewDecodeWriter(w io.Writer) io.WriteCloser
- func NewDecoder(r io.Reader) io.Reader
- func NewEncodeReader(r io.Reader, c *Config) io.Reader
- func NewEncodeTransformer(c *Config) transform.Transformer
- func NewEncoder(w io.Writer, c *Config) io.WriteCloser
- func WordsRequired(length int) int
- type Config
- type UnexpectedEndWordError
- type UnexpectedWordError
- type UnknownWordError
- type WordError
Constants ¶
const WordListVersion = "0.7"
WordListVersion is the version of compiled in word list.
Variables ¶
This section is empty.
Functions ¶
func DecodeWordList ¶
DecodeWordList decodes the mnemonic words in src into bytes which are appended to dst.
func EncodeWordList ¶
EncodeWordList encodes src into mnemomic words which are appended to dst. The final wordlist is returned. There will be WordsRequired(len(src)) words appeneded.
func NewDecodeTransformer ¶
func NewDecodeTransformer() transform.Transformer
NewDecodeTransformer returns a new transform that decodes mnemonic words into the represented bytes. Unrecognized words will trigger an error.
func NewDecodeWriter ¶
func NewDecodeWriter(w io.Writer) io.WriteCloser
NewDecodeWriter returns a new io.WriteCloser that will write decoded bytes from mnemonic words written to it. Unrecognized words will cause a write error. The user needs to call Close to flush unwritten bytes that may be buffered.
func NewDecoder ¶
NewDecoder returns a new io.Reader that will return the decoded bytes from mnemonic words in r. Unrecognized words in r will cause reads to return an error.
func NewEncodeReader ¶
NewEncodeReader returns a new io.Reader that will return a formatted list of mnemonic words representing the bytes in r.
The configuration of the word formatting is controlled by c, which can be nil for default formatting.
func NewEncodeTransformer ¶
func NewEncodeTransformer(c *Config) transform.Transformer
NewEncodeTransformer returns a new transformer that encodes bytes into mnemonic words.
The configuration of the word formatting is controlled by c, which can be nil for default formatting.
func NewEncoder ¶
func NewEncoder(w io.Writer, c *Config) io.WriteCloser
NewEncoder returns a new io.WriteCloser that will write a formatted list of mnemonic words representing the bytes written to w. The user needs to call Close to flush unwritten bytes that may be buffered.
The configuration of the word formatting is controlled by c, which can be nil for default formatting.
func WordsRequired ¶
WordsRequired returns the number of words required to encode input data of length bytes using mnomonic encoding.
Every four bytes of input is encoded into three words. If there is an extra one or two bytes they get an extra one or two words respectively. If there is an extra three bytes, they will be encoded into three words with the last word being one of a small set of very short words (only needed to encode the last 3 bits).
Types ¶
type Config ¶
type Config struct {
LinePrefix string
LineSuffix string
WordSeparator string
GroupSeparator string
WordsPerGroup uint
GroupsPerLine uint
WordPadding rune
}
A Config structure contains options for mneomonic encoding.
{PREFIX}word{wsep}word{gsep}word{wsep}word{SUFFIX}
type UnexpectedEndWordError ¶
type UnexpectedEndWordError string
func (UnexpectedEndWordError) Error ¶
func (e UnexpectedEndWordError) Error() string
func (UnexpectedEndWordError) Word ¶
func (e UnexpectedEndWordError) Word() string
type UnexpectedWordError ¶
type UnexpectedWordError string
func (UnexpectedWordError) Error ¶
func (e UnexpectedWordError) Error() string
func (UnexpectedWordError) Word ¶
func (e UnexpectedWordError) Word() string
type UnknownWordError ¶
type UnknownWordError string
func (UnknownWordError) Error ¶
func (e UnknownWordError) Error() string
func (UnknownWordError) Word ¶
func (e UnknownWordError) Word() string
Source Files
Directories