API Reference

This page provides detailed API documentation for the dtmf_table Python package.

Module Overview

DTMF (Dual-Tone Multi-Frequency) frequency table for telephony applications.

This library provides efficient, const-first mappings between DTMF keys and their canonical frequency pairs. Built with Rust for performance, it offers both exact lookups and tolerance-based matching for real-world audio analysis.

class dtmf_table.DtmfKey

Bases: object

A DTMF (Dual-Tone Multi-Frequency) key representing telephony keypad buttons.

DtmfKey represents one of the 16 standard DTMF keys used in telephony systems: - Digits 0-9 - Special characters * and # - Letters A-D (extended keypad)

Each key corresponds to a unique pair of low and high frequency tones.

Examples

>>> from dtmf_table import DtmfKey
>>> key = DtmfKey.from_char('5')
>>> key.to_char()
'5'
>>> low, high = key.freqs()
>>> (low, high)
(770, 1336)
freqs($self) → tuple[int, int]

–

Get the canonical frequencies for this DTMF key.

Returns:

(low_frequency_hz, high_frequency_hz)

Return type:

tuple[int, int]

static from_char(c: str) → DtmfKey

–

Create a DtmfKey from a character.

Parameters:

c (str) – Single character representing the DTMF key (‘0’-‘9’, ‘*’, ‘#’, ‘A’-‘D’)

Returns:

The corresponding DTMF key

Return type:

DtmfKey

Raises:

ValueError – If the character is not a valid DTMF key

to_char($self) → str

–

Convert the DtmfKey to its character representation.

Returns:

Single character representing the key

Return type:

str

class dtmf_table.DtmfTone

Bases: object

A DTMF tone containing a key and its associated frequency pair.

DtmfTone represents the complete information for a DTMF signal: the key character and its corresponding low and high frequencies. This is useful for iterating over all possible tones or when you need both the key and frequency information together.

Examples

>>> from dtmf_table import DtmfTable
>>> tones = DtmfTable.all_tones()
>>> tone = tones[0]  # First tone
>>> print(tone)
1: (697 Hz, 1209 Hz)
>>> tone.key.to_char()
'1'
>>> (tone.low_hz, tone.high_hz)
(697, 1209)
high_hz

High frequency in Hz.

key

The DTMF key for this tone.

low_hz

Low frequency in Hz.

class dtmf_table.DtmfTable

Bases: object

DTMF frequency lookup table for audio processing applications.

DtmfTable provides efficient bidirectional mapping between DTMF keys and their canonical frequency pairs. It supports exact lookups, tolerance-based matching for real-world audio analysis, and frequency snapping for noisy estimates.

The table contains all 16 standard DTMF frequencies used in telephony:

697 Hz

1

2

3

A

770 Hz

4

5

6

B

852 Hz

7

8

9

C

941 Hz

0

#

D

Examples

Basic usage:

>>> from dtmf_table import DtmfTable, DtmfKey
>>> table = DtmfTable()
>>>
>>> # Forward lookup: key to frequencies
>>> key = DtmfKey.from_char('5')
>>> low, high = table.lookup_key(key)
>>> (low, high)
(770, 1336)

Real-world audio analysis:

>>> # Reverse lookup with tolerance (from FFT peaks)
>>> key = table.from_pair_tol_f64(770.2, 1335.8, 5.0)
>>> key.to_char() if key else None
'5'
>>>
>>> # Snap noisy frequencies to nearest canonical values
>>> key, low, high = table.nearest_u32(768, 1340)
>>> (key.to_char(), low, high)
('5', 770, 1336)
static all_keys() → list[DtmfKey]

–

Get all DTMF keys in keypad order.

Returns:

All 16 DTMF keys

Return type:

list[DtmfKey]

static all_keys_matrix() → list[list[DtmfKey]]

–

Get all DTMF keys as a 4x4 matrix.

Returns:

4x4 matrix of keys in keypad layout

Return type:

list[list[DtmfKey]]

static all_tones() → list[DtmfTone]

–

Get all DTMF tones in keypad order.

Returns:

All 16 DTMF tones

Return type:

list[DtmfTone]

static all_tones_matrix() → list[list[DtmfTone]]

–

Get all DTMF tones as a 4x4 matrix.

Returns:

4x4 matrix of tones in keypad layout

Return type:

list[list[DtmfTone]]

static from_pair_exact(low: int, high: int) → DtmfKey | None

–

Find DTMF key from exact frequency pair.

Parameters:

  • low (int) – Low frequency in Hz

  • high (int) – High frequency in Hz

Returns:

The matching key, or None if no exact match

Return type:

DtmfKey or None

static from_pair_normalised(a: int, b: int) → DtmfKey | None

–

Find DTMF key from frequency pair with automatic order normalization.

Parameters:

  • a (int) – First frequency in Hz

  • b (int) – Second frequency in Hz

Returns:

The matching key, or None if no exact match

Return type:

DtmfKey or None

from_pair_tol_f64($self, low: float, high: float, tol_hz: float) → DtmfKey | None

–

Find DTMF key from frequency pair with tolerance (float version).

Parameters:

  • low (float) – Low frequency in Hz

  • high (float) – High frequency in Hz

  • tol_hz (float) – Tolerance in Hz

Returns:

The matching key within tolerance, or None

Return type:

DtmfKey or None

from_pair_tol_u32(low: int, high: int, tol_hz: int) → DtmfKey | None

–

Find DTMF key from frequency pair with tolerance (integer version).

Parameters:

  • low (int) – Low frequency in Hz

  • high (int) – High frequency in Hz

  • tol_hz (int) – Tolerance in Hz

Returns:

The matching key within tolerance, or None

Return type:

DtmfKey or None

static lookup_key(key: DtmfKey) → tuple[int, int]

–

Look up frequencies for a given key.

Parameters:

key (DtmfKey) – The DTMF key to look up

Returns:

(low_frequency_hz, high_frequency_hz)

Return type:

tuple[int, int]

nearest_f64($self, low: float, high: float) → tuple[DtmfKey, int, int]

–

Find the nearest DTMF key and snap frequencies to canonical values (float version).

Parameters:

  • low (float) – Low frequency estimate in Hz

  • high (float) – High frequency estimate in Hz

Returns:

(key, snapped_low_hz, snapped_high_hz)

Return type:

tuple[DtmfKey, int, int]

nearest_u32($self, low: int, high: int) → tuple[DtmfKey, int, int]

–

Find the nearest DTMF key and snap frequencies to canonical values (integer version).

Parameters:

  • low (int) – Low frequency estimate in Hz

  • high (int) – High frequency estimate in Hz

Returns:

(key, snapped_low_hz, snapped_high_hz)

Return type:

tuple[DtmfKey, int, int]

Constants

dtmf_table.LOWS

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

dtmf_table.HIGHS

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

DtmfKey

class dtmf_table.DtmfKey

Bases: object

A DTMF (Dual-Tone Multi-Frequency) key representing telephony keypad buttons.

DtmfKey represents one of the 16 standard DTMF keys used in telephony systems: - Digits 0-9 - Special characters * and # - Letters A-D (extended keypad)

Each key corresponds to a unique pair of low and high frequency tones.

Examples

>>> from dtmf_table import DtmfKey
>>> key = DtmfKey.from_char('5')
>>> key.to_char()
'5'
>>> low, high = key.freqs()
>>> (low, high)
(770, 1336)
freqs($self) → tuple[int, int]

–

Get the canonical frequencies for this DTMF key.

Returns:

(low_frequency_hz, high_frequency_hz)

Return type:

tuple[int, int]

static from_char(c: str) → DtmfKey

–

Create a DtmfKey from a character.

Parameters:

c (str) – Single character representing the DTMF key (‘0’-‘9’, ‘*’, ‘#’, ‘A’-‘D’)

Returns:

The corresponding DTMF key

Return type:

DtmfKey

Raises:

ValueError – If the character is not a valid DTMF key

to_char($self) → str

–

Convert the DtmfKey to its character representation.

Returns:

Single character representing the key

Return type:

str

DtmfTone

class dtmf_table.DtmfTone

Bases: object

A DTMF tone containing a key and its associated frequency pair.

DtmfTone represents the complete information for a DTMF signal: the key character and its corresponding low and high frequencies. This is useful for iterating over all possible tones or when you need both the key and frequency information together.

Examples

>>> from dtmf_table import DtmfTable
>>> tones = DtmfTable.all_tones()
>>> tone = tones[0]  # First tone
>>> print(tone)
1: (697 Hz, 1209 Hz)
>>> tone.key.to_char()
'1'
>>> (tone.low_hz, tone.high_hz)
(697, 1209)
high_hz

High frequency in Hz.

key

The DTMF key for this tone.

low_hz

Low frequency in Hz.

DtmfTable

class dtmf_table.DtmfTable

Bases: object

DTMF frequency lookup table for audio processing applications.

DtmfTable provides efficient bidirectional mapping between DTMF keys and their canonical frequency pairs. It supports exact lookups, tolerance-based matching for real-world audio analysis, and frequency snapping for noisy estimates.

The table contains all 16 standard DTMF frequencies used in telephony:

697 Hz

1

2

3

A

770 Hz

4

5

6

B

852 Hz

7

8

9

C

941 Hz

0

#

D

Examples

Basic usage:

>>> from dtmf_table import DtmfTable, DtmfKey
>>> table = DtmfTable()
>>>
>>> # Forward lookup: key to frequencies
>>> key = DtmfKey.from_char('5')
>>> low, high = table.lookup_key(key)
>>> (low, high)
(770, 1336)

Real-world audio analysis:

>>> # Reverse lookup with tolerance (from FFT peaks)
>>> key = table.from_pair_tol_f64(770.2, 1335.8, 5.0)
>>> key.to_char() if key else None
'5'
>>>
>>> # Snap noisy frequencies to nearest canonical values
>>> key, low, high = table.nearest_u32(768, 1340)
>>> (key.to_char(), low, high)
('5', 770, 1336)
static all_keys() → list[DtmfKey]

–

Get all DTMF keys in keypad order.

Returns:

All 16 DTMF keys

Return type:

list[DtmfKey]

static all_keys_matrix() → list[list[DtmfKey]]

–

Get all DTMF keys as a 4x4 matrix.

Returns:

4x4 matrix of keys in keypad layout

Return type:

list[list[DtmfKey]]

static all_tones() → list[DtmfTone]

–

Get all DTMF tones in keypad order.

Returns:

All 16 DTMF tones

Return type:

list[DtmfTone]

static all_tones_matrix() → list[list[DtmfTone]]

–

Get all DTMF tones as a 4x4 matrix.

Returns:

4x4 matrix of tones in keypad layout

Return type:

list[list[DtmfTone]]

static from_pair_exact(low: int, high: int) → DtmfKey | None

–

Find DTMF key from exact frequency pair.

Parameters:

  • low (int) – Low frequency in Hz

  • high (int) – High frequency in Hz

Returns:

The matching key, or None if no exact match

Return type:

DtmfKey or None

static from_pair_normalised(a: int, b: int) → DtmfKey | None

–

Find DTMF key from frequency pair with automatic order normalization.

Parameters:

  • a (int) – First frequency in Hz

  • b (int) – Second frequency in Hz

Returns:

The matching key, or None if no exact match

Return type:

DtmfKey or None

from_pair_tol_f64($self, low: float, high: float, tol_hz: float) → DtmfKey | None

–

Find DTMF key from frequency pair with tolerance (float version).

Parameters:

  • low (float) – Low frequency in Hz

  • high (float) – High frequency in Hz

  • tol_hz (float) – Tolerance in Hz

Returns:

The matching key within tolerance, or None

Return type:

DtmfKey or None

from_pair_tol_u32(low: int, high: int, tol_hz: int) → DtmfKey | None

–

Find DTMF key from frequency pair with tolerance (integer version).

Parameters:

  • low (int) – Low frequency in Hz

  • high (int) – High frequency in Hz

  • tol_hz (int) – Tolerance in Hz

Returns:

The matching key within tolerance, or None

Return type:

DtmfKey or None

static lookup_key(key: DtmfKey) → tuple[int, int]

–

Look up frequencies for a given key.

Parameters:

key (DtmfKey) – The DTMF key to look up

Returns:

(low_frequency_hz, high_frequency_hz)

Return type:

tuple[int, int]

nearest_f64($self, low: float, high: float) → tuple[DtmfKey, int, int]

–

Find the nearest DTMF key and snap frequencies to canonical values (float version).

Parameters:

  • low (float) – Low frequency estimate in Hz

  • high (float) – High frequency estimate in Hz

Returns:

(key, snapped_low_hz, snapped_high_hz)

Return type:

tuple[DtmfKey, int, int]

nearest_u32($self, low: int, high: int) → tuple[DtmfKey, int, int]

–

Find the nearest DTMF key and snap frequencies to canonical values (integer version).

Parameters:

  • low (int) – Low frequency estimate in Hz

  • high (int) – High frequency estimate in Hz

Returns:

(key, snapped_low_hz, snapped_high_hz)

Return type:

tuple[DtmfKey, int, int]