flutter_dtmf_pro - Dart API docs

Excellent — here’s a professional, full-length README.md for your new package flutter_dtmf_pro, written in the style of a seasoned Flutter plugin engineer.

This version highlights your modernizations (Gradle, Kotlin, Web), includes working examples, platform notes, and installation instructions.

# flutter_dtmf_pro

[![pub package](https://img.shields.io/pub/v/flutter_dtmf_pro.svg)](https://pub.dev/packages/flutter_dtmf_pro)
[![Flutter Platform](https://img.shields.io/badge/platform-Flutter-blue.svg)](https://flutter.dev)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> A modernized Flutter plugin for generating **DTMF (Dual-Tone Multi-Frequency)** tones across Android, iOS, and Web platforms.  
> Useful for **VoIP**, **dialer**, **telephony**, or **tone-based signaling** applications.

---

## ✨ Features

- 🎵 Generate DTMF tones from any string of digits (`0–9`, `A–D`, `*`, `#`)
- ⚙️ Configurable tone **duration**, **volume**, and **sampling rate**
- 📱 Native Android implementation via [`ToneGenerator`](https://developer.android.com/reference/android/media/ToneGenerator)
- 🌐 Web-compatible implementation using the Web Audio API (`package:web`)
- 🧩 Compatible with **Flutter 3.24+**, **Kotlin 1.9+**, and **Gradle 9.1+**
- 🧱 Clean architecture & null-safety support

---

## 🚀 Installation

Add the dependency in your project’s `pubspec.yaml`:

```yaml
dependencies:
  flutter_dtmf_pro: ^1.0.0

Then run:

flutter pub get

Import it in your Dart code:

import 'package:flutter_dtmf_pro/flutter_dtmf_pro.dart';

🧠 Usage Examples

Play multiple tones in sequence:

await Dtmf.playTone(
  digits: "1234567890ABCD*#",
  durationMs: 500,    // duration per tone (milliseconds)
  volume: 0.8,        // 0.0 to 1.0
);

Play a single tone with a custom sampling rate:

await Dtmf.playTone(
  digits: "1",
  samplingRate: 80000.0, // custom tone precision
);

Stop playing (if applicable on platform):

await Dtmf.stopTone();

🧩 Platform Support

Platform	Status	Implementation
Android	✅	Uses `ToneGenerator` API
iOS	⚙️ Planned	Native audio implementation in progress
Web	✅	Uses Web Audio API via `package:web`
macOS / Windows / Linux	⚙️ Planned	Cross-platform tone synthesis under consideration

⚙️ Parameters

Parameter	Type	Default	Description
`digits`	`String`	–	DTMF sequence to play (`0–9`, `A–D`, `*`, `#`)
`durationMs`	`int`	160	Duration of each tone in milliseconds
`volume`	`double`	1.0	Volume of playback (0.0–1.0)
`samplingRate`	`double`	44100.0	Sampling rate for audio generation
`forceMaxVolume`	`bool`	false	Forces tone playback at max volume (Android only)
`ignoreDtmfSystemSettings`	`bool`	false	Bypasses system DTMF controls (Android only)

📦 Example App

A complete Flutter example is included in /example. Run it with:

cd example
flutter run

This demonstrates tone generation for all supported characters.

🧱 Android Notes

Uses android.media.ToneGenerator
Requires android.permission.MODIFY_AUDIO_SETTINGS in AndroidManifest.xml (automatically handled in most cases)
Compatible with minSdkVersion 21 and compileSdkVersion 34

🌐 Web Notes

Uses AudioContext from the Web Audio API
Requires the web dependency:
```
dependencies:
  web: ^1.0.0
```
Supported on Chrome, Edge, and Safari.

🧾 Changelog

See CHANGELOG.md for the complete release history.

🧑‍💻 Contributing

Contributions, pull requests, and issue reports are welcome! Please ensure changes pass dart analyze and flutter test before submission.

📄 License

🔮 Roadmap

x Android implementation via ToneGenerator
x Web implementation via package:web
iOS native tone generation
Windows / Linux support
Continuous tone stream API

Made with ❤️ in Flutter — bringing clear, crisp tones to your apps.


---

Would you like me to generate a **shortened pub.dev description block** (under 200 characters, ideal for `pubspec.yaml`) based on this README? That ensures it looks perfect on the pub.dev listing page.