Metadata-Version: 2.4
Name: dtmf-tone-pure
Version: 0.1.0
Summary: Zero-dependency DTMF tone generator producing RFC 4733-compliant WAV bytes in pure stdlib Python
License: MIT
Project-URL: Home, https://github.com/prasad-a-abhishek/dtmf-tone-pure
Project-URL: Source, https://github.com/prasad-a-abhishek/dtmf-tone-pure
Keywords: dtmf,tone,goertzel,wav,voip,phone
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# dtmf-tone-pure

**Zero-dependency DTMF tone generator — pure stdlib Python, RFC 4733-compliant WAV output.**

Generate all 16 ITU Q.23/Q.24 DTMF tones as WAV bytes using only `math` and `struct`. No numpy, no C extensions, no dependencies. Designed for AWS Lambda, Cloudflare Workers, and embedded Python.

---

## Quick Start

```bash
pip install dtmf-tone-pure
```

```python
from dtmf_tone_pure import DTMFTone

tone = DTMFTone().tone('5')       # Single tone, 44+ bytes of WAV
tones = DTMFTone().tones('911')   # Multi-digit with 10ms inter-digit pause
coeff = DTMFTone().goertzel_coefficient(697, block_size=120)  # Goertzel coefficient
```

**Install from source:**
```bash
pip install git+https://github.com/prasad-a-abhishek/dtmf-tone-pure.git
```

**Run tests:**
```bash
pip install -e .
pytest tests/ -v
```

---

## Why dtmf-tone-pure?

Every existing DTMF library for Python depends on numpy or C extensions. In serverless environments (AWS Lambda cold start ~50ms for numpy import, ~50MB memory), that's prohibitive.

`dtmf-tone-pure` fills the gap: the only zero-dependency Python package on PyPI that **generates** DTMF tones as RFC 4733-compliant WAV bytes. (`pydtmf` on PyPI does detection only.)

| Package | PyPI | Generation | Dependencies |
|---------|------|-----------|--------------|
| `dtmf-tone-pure` | Yes (this) | Yes | **None** |
| `pydtmf` | Yes | No (detection only) | None |
| numpy scripts | Various | Yes | numpy |

---

## Key Features

- **16 DTMF tones**: 0–9, A–D, `*`, `#` per ITU Q.23/Q.24
- **Zero dependencies**: pure stdlib — `math`, `struct`, `typing` only
- **WAV output**: 8 kHz, 16-bit mono PCM with correct RIFF header
- **Goertzel coefficient**: `goertzel_coefficient(freq, block_size)` matching analytical values
- **ITU-spec durations**: 60ms tone, 10ms inter-digit pause
- **Subclassable**: override `FREQ_TABLE` for custom frequency pairs

---

## API Reference

```python
from dtmf_tone_pure import DTMFTone

dtmf = DTMFTone()

# Class constants
dtmf.SAMPLE_RATE      # 8000 Hz
dtmf.TONE_DURATION    # 0.060 s (60 ms)
dtmf.PAUSE_DURATION   # 0.010 s (10 ms)
dtmf.FREQ_TABLE       # {'1': (697.0, 1209.0), ...} — 16 entries

# Methods
dtmf.tone(key: str) -> bytes
    # Single DTMF tone as WAV bytes.
    # key: '0'-'9', 'A'-'D', '*', '#'
    # Returns: 44-byte RIFF WAV header + PCM samples

dtmf.tones(digits: str) -> bytes
    # Concatenated tones with 10ms inter-digit silence.
    # Returns: single valid WAV file

dtmf.goertzel_coefficient(freq: float, *, block_size: int = 120) -> float
    # Goertzel coefficient = 2 * cos(2π * k / N)
    # k = round(N * freq / sample_rate)
    # Returns: float rounded to 6 decimal places
```

**DTMF Frequency Table (ITU Q.23/Q.24):**

|        | 1209 Hz | 1336 Hz | 1477 Hz | 1633 Hz |
|--------|---------|---------|---------|---------|
| 697 Hz | 1       | 2       | 3       | A       |
| 770 Hz | 4       | 5       | 6       | B       |
| 852 Hz | 7       | 8       | 9       | C       |
| 941 Hz | *       | 0       | #       | D       |

---

## Limitations

- Single sample rate (8000 Hz). Custom rates require subclassing and recomputing.
- Amplitude is fixed at 16383.5 scale factor (max sum-of-two-sines → max int16).
- `tones()` returns a single concatenated WAV; no gapless-playback marker between segments.
- Goertzel coefficient precision is rounded to 6 decimal places.

---

## Non-Goals

- CLI interface (see `goertzel-tone-pure` CLI wrapper if needed)
- Tone **detection** (use `pydtmf` for that)
- numpy/scipy acceleration
- Multiple sample rates or bit depths beyond 8kHz/16-bit mono

---

## License

MIT — see [LICENSE](LICENSE).
