pitch_kit 0.0.1

Real-time chord and note detection from the device microphone, built on a pure Dart DSP core.

pitch_kit

✨ Features

A modern and easy-to-use Flutter package for real-time chord and note detection straight from the device microphone, with a pure Dart DSP core:

• 🎸 Note Detection – Detect individual notes (E, A, D, G, B, …) with the YIN pitch-detection algorithm for accurate, octave-error-resistant results.
• 🎶 Chord Detection – Recognize chords such as Am, Bb, C, Em7, and Asus2 using chroma analysis and template matching.
• 🎚️ Tuning in Cents – Every detected note reports how flat or sharp it is, ready to drive a tuner needle.
• 🎻 Multi-Instrument Ready – Built-in InstrumentProfile presets (Guitar, Ukulele, Bass), or supply your own custom tuning.
• 🔇 Noise Handling – DC-offset removal, a high-pass filter, an energy gate, and temporal smoothing reduce background interference.
• ⚡ Real-Time & Efficient – A from-scratch FFT and Stream-based pipeline, with a bounded pitch-detection search, keep detection fast and responsive.
• 🚀 Flutter Widget Support – A single widget handles the microphone permission (including the permanently-denied → Settings flow) and streams results back to you.

🚀 Getting started

Requirements

Requirement	Version
Dart SDK	≥ 3.0.0
Flutter SDK	≥ 3.10.0
Android — min SDK	28
Android — target SDK	37
iOS — min deployment	15.0

Tested on Flutter 3.47.2 / Dart 3.13.2.

Add the package to your pubspec.yaml:

dependencies:
  pitch_kit: ^0.0.1

Or install it from the command line:

flutter pub add pitch_kit

This package depends on record for microphone capture and permission_handler for the runtime permission flow. Both are pulled in automatically.

📱 Platform Setup

pitch_kit needs microphone access. Setup differs by platform.

Android

No action needed. pitch_kit already declares android.permission.RECORD_AUDIO in its manifest, so it merges into your app automatically.

iOS

1. Add the usage description to ios/Runner/Info.plist. Without it, iOS terminates the app the instant it accesses the microphone:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access to detect notes and chords from your instrument.</string>

2. permission_handler compiles every permission unless you opt out. In ios/Podfile, enable only the microphone macro inside the post_install block:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        'PERMISSION_MICROPHONE=1',
        'PERMISSION_EVENTS=0',
        'PERMISSION_EVENTS_FULL_ACCESS=0',
        'PERMISSION_REMINDERS=0',
        'PERMISSION_CONTACTS=0',
        'PERMISSION_CAMERA=0',
        'PERMISSION_PHOTOS=0',
        'PERMISSION_NOTIFICATIONS=0',
        'PERMISSION_MEDIA_LIBRARY=0',
        'PERMISSION_SENSORS=0',
        'PERMISSION_BLUETOOTH=0',
        'PERMISSION_APP_TRACKING_TRANSPARENCY=0',
        'PERMISSION_CRITICAL_ALERTS=0',
        'PERMISSION_ASSISTANT=0',
        'PERMISSION_LOCATION=0',
        'PERMISSION_SPEECH_RECOGNIZER=0',
      ]
    end
  end
end

💡 Usage

The example below shows a minimal integration. See the example project for the full app.

🎸 GuitarTunerListener

Wrap any widget with GuitarTunerListener. It requests the microphone permission, starts detection, and streams a typed TuningResult back through the onResult callback. Detection stops automatically when the widget is disposed.

Parameters	Description
onResult	This parameter is required and it's the callback invoked with each detection result (NoteTuningResult, ChordTuningResult, or SilenceTuningResult)
child	This parameter is required and it's the widget rendered while the tuner runs in the background
profile	This parameter is the InstrumentProfile to tune for, with default value InstrumentProfile.guitar (built-in: .guitar, .ukulele, .bass)
titleText	This parameter is the title text of the permission popup with default value "Microphone needed"
rationaleText	This parameter is the text shown when the permission can still be requested
permanentlyDeniedText	This parameter is the text shown when the permission is permanently denied (the button then opens Settings)
allowText	This parameter is the confirm button label when the permission can still be requested with default value "Allow"
openSettingsText	This parameter is the confirm button label when the permission is permanently denied with default value "Open Settings"
dismissText	This parameter is the dismiss button label with default value "Not now"

🎶 TuningResult

TuningResult is a sealed class with three cases you can handle exhaustively:

Type	Description
NoteTuningResult	A single detected note: name (e.g. "E", "A#"), freq (Hz), and cents (deviation, -50..+50)
ChordTuningResult	A detected chord: name (e.g. "Am", "Cmaj7")
SilenceTuningResult	No sound / below the detection threshold

🎻 InstrumentProfile

Parameters	Description
name	This parameter is required and it's the human-readable label, e.g. "Guitar"
minFreq	This parameter is required and it's the lowest frequency (Hz) analysis considers
maxFreq	This parameter is required and it's the highest frequency (Hz) considered for chroma
bassCeiling	This parameter is required and it's the ceiling (Hz) for the chord bass-note scan
harmonicPivot	This parameter is required and it's the frequency (Hz) around which harmonic down-weighting is centred
openStrings	This parameter is required and it's the list of OpenString values for the instrument's standard tuning
rmsGate	This parameter is the loudness gate (RMS); frames quieter than this are treated as silence, default value 0.01
useFlats	This parameter is the option to display flats (Bb) instead of sharps (A#), default value false

import 'package:flutter/material.dart';
import 'package:pitch_kit/pitch_kit.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Pitch Kit',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6200EE)),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  String _resultNote = '-';
  double _resultFreq = 0.0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text(
          'Pitch Kit',
          style: TextStyle(fontWeight: FontWeight.bold),
        ),
        centerTitle: true,
      ),
      // ==========================================
      // 1. Start the tuner
      // ==========================================
      body: GuitarTunerListener(
        profile: InstrumentProfile.guitar,
        onResult: (result) {
          setState(() {
            _resultFreq = result is NoteTuningResult ? result.freq : 0.0;
            _resultNote = switch (result) {
              NoteTuningResult() => result.name,
              ChordTuningResult() => result.name,
              SilenceTuningResult() => '-',
            };
          });
        },
        // ==========================================
        // 2. Render your UI
        // ==========================================
        child: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(
                _resultNote,
                style: const TextStyle(
                  fontSize: 96,
                  fontWeight: FontWeight.bold,
                ),
              ),
              if (_resultFreq > 0)
                Text(
                  '${_resultFreq.toStringAsFixed(1)} Hz',
                  style: const TextStyle(fontSize: 20, color: Colors.grey),
                ),
            ],
          ),
        ),
      ),
    );
  }
}

🎼 Custom Tuning

You can supply your own InstrumentProfile for non-standard tunings:

const dropD = InstrumentProfile(
  name: 'Drop D',
  minFreq: 60.0,
  maxFreq: 5000.0,
  bassCeiling: 400.0,
  harmonicPivot: 200.0,
  openStrings: [
    OpenString('D2', 73.42),
    OpenString('A2', 110.00),
    OpenString('D3', 146.83),
    OpenString('G3', 196.00),
    OpenString('B3', 246.94),
    OpenString('E4', 329.63),
  ],
);

GuitarTunerListener(
  profile: dropD,
  onResult: (result) {
    //...your code here
  },
  child: const SizedBox(),
);

🎹 Supported Chords

Each of the 12 roots is combined with the following qualities: major, minor (m), dominant 7th (7), minor 7th (m7), major 7th (maj7), sus2, sus4, diminished (dim), and augmented (aug).

Examples: C, Am, G7, Em7, Dmaj7, Asus2, Bdim, Faug.

ℹ️ Additional information

Thank you for using pitch_kit! Your feedback helps make this package better. If you encounter any bugs or unexpected behavior, please open an issue on the GitHub repository.