Console/terminal demo of a simple spoken-word recognizer, supporting Windows 11 and Ubuntu Linux 24.04. A small Keras CNN over MFCC features recognizes the words bed, cat and happy from one-second wav clips. MFCC turns the audio into a spectral representation close to how human hearing works, which is the usual input for speech models. The dataset (5,076 files, a 3-class subset of Google Speech Commands) and a trained checkpoint (model/cp-3000.ckpt) ship with the project, so inference works out of the box on a single wav, a whole folder or a live microphone. Based on DeadSimpleSpeechRecognizer (MIT).

 

[Folder Structure]

  • CLAUDE.md / AGENT.md: program specification (identical content).
  • CHANGELOG.md: change log.
  • copyright.txt: copyright notice.
  • LICENSE / README.upstream.md: the upstream MIT license and README.
  • data/speech_commands/: the wav files, bed (1,665), cat (1,691) and happy (1,720). Training also caches the MFCC features here as .npy files.
  • model/: the shipped weights cp-3000.ckpt and pre_cp-3000.ckpt. New checkpoints go to model/train/ and microphone recordings to model/microphone/.
  • tool/tools.py: shared helpers.
  • src/: the scripts, the launcher scripts and this document.
  • venv/: Python virtual environment, created by step 1.

[Prerequisites]

  • Operating system: Windows 11 or Ubuntu Linux 24.04.
  • Python 3.10 to 3.13; TensorFlow has no 3.14 wheels yet.
  • The model is tiny, so the CPU is fine for both training and inference. On Linux, GPU users can install tensorflow[and-cuda].
  • Dependencies (TensorFlow, tf-keras, librosa, scikit-learn, tqdm, numpy) are listed in src/requirements.txt and installed by step 1.
  • The microphone mode needs PyAudio. On Ubuntu, install portaudio19-dev first.

[Instructions]

Step 1: create the virtual environment

Delete the old venv/, create a fresh one and install src/requirements.txt; it aborts loudly if pip fails. It then installs PyAudio best-effort, which only the microphone mode needs, so everything else still works if that part fails.

 

Windows 11: src\01_venv_create.bat

Ubuntu 24.04: sudo apt install portaudio19-dev

Ubuntu 24.04: bash src/01_venv_create.sh

 

Step 2: activate the virtual environment

Activate the venv you just created. On Linux, source it so the environment variables apply to the current shell.

 

Windows 11: src\02_venv_activate.bat

Ubuntu 24.04: source src/02_venv_activate.sh

 

Step 3: recognize one wav file

Recognize a single wav with the shipped weights; a bed sample is used by default.

 

Windows 11: src\04_inference.bat

Ubuntu 24.04: bash src/04_inference.sh

 

Step 4: recognize a whole folder

Recognize every wav in a folder, the happy class by default. Add --limit to cap how many files are processed.

 

Windows 11: src\05_inference_folder.bat

Ubuntu 24.04: bash src/05_inference_folder.sh --limit 20

 

Step 5: recognize live microphone audio (optional)

Recognize the microphone in roughly one-second chunks. PyAudio is required; press Ctrl+C to stop early.

 

Windows 11: src\06_inference_microphone.bat

Ubuntu 24.04: bash src/06_inference_microphone.sh --seconds 5

 

Step 6: train the model (optional)

Retrain the CNN. The checkpoints go to model/train/ and the shipped model/cp-3000.ckpt is never overwritten.

 

Windows 11: src\03_train.bat

Ubuntu 24.04: bash src/03_train.sh --epochs 50

 

Step 7: clear the virtual environment (optional)

Delete the venv/ folder to free disk space when you no longer need it.

 

Windows 11: src\99_venv_clear.bat

Ubuntu 24.04: bash src/99_venv_clear.sh

 

[Python Entry Points]

  • src/train.py: [--dataset data/speech_commands] [--epochs 1000] [--batch-size 100] [--pretrained CKPT] [--save-dir model/train] [--reuse-cache]. It extracts the MFCC features (cached as .npy), splits the data 60/40, trains, and saves one cp-{epoch}.ckpt per epoch.
  • src/inference.py: [--wav FILE] [--model model/cp-3000.ckpt] [--dataset ...]. Prints the predicted word.
  • src/inference_folder.py: [--folder data/speech_commands/happy] [--model ...] [--limit 0]. Prints the path and the predicted word for every wav.
  • src/inference_microphone.py: [--seconds 10] [--model ...] [--output-dir model/microphone]. Recognizes roughly one-second chunks live; Ctrl+C stops early.

[Usage Notes]

  • The scripts set TF_USE_LEGACY_KERAS=1 internally and run the legacy Keras 2 (tf-keras), because Keras 3 cannot load the shipped checkpoint format. TensorFlow prints some harmless deprecation warnings as a result; the predictions are unaffected.
  • PyAudio is only needed for the microphone mode and is installed best-effort, so if it fails (missing PortAudio headers on Linux) everything else still works.
  • To recognize different words, put new class folders of one-second wavs under data/speech_commands/ and retrain; the labels are the sorted folder names.

[References]

 

This SDK is built in AppForAI - AI Dev Tools.

 

Purchase license separately:  USD 600, permanent authorization, single APP authorization, single machine authorization, one-year activation, one-year download, one-year update, one-year email technical support.