Table of contents

AudioTranscript: From WAV chunks to transcription

AudioTranscript breaks a WAV recording into chunks around silence, sends each chunk to a recognition service and concatenates the results. The current implementation uses Amazon recognition, even though its docstrings still mention Google.

Application and tools

Updated 2026-10-23
1
Python · 100%
MIT

Python

View source README Markdown

Languages: 1Code breakdown
Documented components: 2Explore modules
Source documents: 1Read the instructions

Repository languagesPython 100%1

Shares calculated from GitHub Linguist bytes.

Python100%

100%6,443 bytes

Language	%	Bytes
Python	100%	6,443

GitHub README Language statistics

1. Overview

1.1. Why it exists

Audio ingestion and transcription worker pipeline with timestamp alignment.

1.2. Best fit

Batch automated audio recording transcription and indexing.

2. Use cases

Python CLI that splits a WAV file on silence and transcribes each chunk into a single text.

People on the left, external systems on the right; each oval is a use case backed by the files cited below.

Split audio on silence: CLI user
main.py loads the WAV with pydub and calls split_on_silence with --min-silence-len, --silence-thresh (relative to the file’s dBFS) and --keep-silence, writing each piece to audio-chunks/chunkN.wav.
Transcribe the chunks: CLI userAmazon Transcribe
Each chunk goes to recognize_amazon (us-east-1, S3 bucket from .env) and the texts are joined and printed. The README describes Google Speech Recognition, but the code calls Amazon; the --language option is not passed on.
Set AWS keys in .env: CLI userAmazon Transcribe
load_dotenv reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_BUCKET_NAME; main.py raises an error if one is missing.
Try Whisper on a sample: CLI userHugging Face Hub
ai.py is a separate script that loads openai/whisper-large-v2 with transformers and transcribes one LibriSpeech dummy sample; it is not wired to the CLI and its packages are not in requirements.txt.

2.1. Scenario: Transcribe a recorded interview

Run pip install -r requirements.txt, plus python-dotenv, which main.py imports but the file does not list.
Create a .env file with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_BUCKET_NAME.
Run python main.py interview.wav -m 700 -s -16 (the path is positional and defaults to caro.wav).
main.py writes the chunks to audio-chunks/ and shows a Rich progress bar.
Each chunk is sent to Amazon Transcribe and the full text is printed at the end.

Files readREADME.mdmain.pyai.pyrequirements.txt

3. Getting started

These commands come from the repository documentation. They were not run during this review.

README.md · Usage

python main.py --path <audio_file_path> --min-silence-len <min_silence_length> --silence-thresh <silence_threshold> --keep-silence <keep_silence_duration> --language <language_code>

4. Repository references

Excerpts from the repository’s guides, in their original language. Links open the inspected source revision.

Prerequisites and first run

4.1. Requirements

README.md

Python 3.x
pydub
speech_recognition
rich
typer
dotenv

Read the full instructions ↗

4.2. Installation

README.md

Clone the repository
Navigate to the project directory
Install the required packages
Create a .env file and add your AWS credentials

Read the full instructions ↗

Configuration and usage

4.3. Usage

README.md

To run the CLI application, navigate to the project directory and run the following command:

Read the full instructions ↗

4.4. Parameters:

README.md

–path: Path of the audio file to transcribe.
–min-silence-len: Minimum length of silence required to detect the end of a speech segment in milliseconds.
–silence-thresh: Threshold value in dBFS below which the audio is considered silent.
–keep-silence: Duration of silence to be kept at the beginning and end of each chunk in milliseconds.
–language: Language code of the audio file to be transcribed.

Read the full instructions ↗

Development and contributions

4.5. Contributing

README.md

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Read the full instructions ↗

Source documentation

README.md

1 documents read from 1 candidates.

5. Features and components 2

Audio segmentation: main.py loads a WAV through pydub and calls split_on_silence. The threshold is calculated relative to the recording’s dBFS level. Each chunk is exported to audio-chunks before recognition.
Recognition and output: A SpeechRecognition Recognizer reads each exported file and calls recognize_amazon. The loop appends the returned text to whole_text, which is printed and returned. Typer exposes the file and segmentation parameters.

6. Architecture

Expand a component to follow its connections, or explore the full diagram.

System components Context

WAV recording
- To pydub silence split
pydub silence split
- From WAV recording
- To Temporary WAV chunks
Temporary WAV chunks
- From pydub silence split
- To Amazon recognition
Amazon recognition
- From Temporary WAV chunks
- To Combined text
Combined text
- From Amazon recognition

Mermaid Interactive diagram

System overview of the components and connections verified in the repository.

Static architecture view for AudioTranscript — Static preview. The interactive diagram replaces it after Mermaid loads.

flowchart LR
  n0["WAV recording"]
  n1["pydub silence split"]
  n2["Temporary WAV chunks"]
  n3["Amazon recognition"]
  n4["Combined text"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4

Text version of the diagram

WAV recording → pydub silence split
pydub silence split → Temporary WAV chunks
Temporary WAV chunks → Amazon recognition
Amazon recognition → Combined text

Follow one path through the code

Follow transcribe_audio_file rather than its docstring: the function checks AWS environment variables immediately before recognize_amazon. Its language argument is exposed by the CLI but is not passed into that call.

7. Technical dossier

Built from the source at commit 91b458e (4 files). Each item comes from a pattern match in the code, so open the linked file before relying on it.

7.1. Layers and modules

Folders are sorted into layers by name, from the user interface down to data access. Because the sorting uses names only, the diagram says nothing about calls between layers.

Mermaid Layered view

flowchart TB
  subgraph L_interface["Entry points and API"]
    direction TB
    interface_0["(root)<br/>1 file"]
  end
  subgraph L_core["Core source"]
    direction TB
    core_0["(root)<br/>1 file"]
  end
  L_interface ~~~ L_core

Modules and their main layer
Module	Layer	Files	Types	Extensions
`(root)`	Core source	2	0	.py

7.2. C4 model

From system context to code declarations. Each level reflects the available source evidence.

UML 1 · System context

The widest C4 view: who uses the project and which outside systems and data stores it relies on. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System(SYS, "AudioTranscript", "AudioTranscript breaks a WAV recording into chunks around silence, se…")
System_Ext(E0, "Hugging Face")
Rel(P_cli, SYS, "Uses")
Rel(SYS, E0, "Calls")
@enduml

UML 2 · Containers

One level closer: the parts that run separately inside the project, their main language and how calls flow between them. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Container>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System_Boundary(SYS, "AudioTranscript") {
  Container(APP, "AudioTranscript", "Python")
}
System_Ext(E0, "Hugging Face")
Rel(P_cli, APP, "Uses")
Rel(APP, E0, "Calls")
@enduml

UML 3 · Components and layers

Modules grouped by source-layer classification. Boundaries show organization, not runtime isolation or call relationships. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "AudioTranscript") {
Boundary(L0, "Entry points and API", "layer") {
Component(M0_0, "(root)", "Python", "1 files")
}
Boundary(L1, "Core source", "layer") {
Component(M1_0, "(root)", "Python", "1 files")
}
}
@enduml

UML 4 · Code

Selected declarations, fields and methods grouped by source file. No inheritance or call edges are inferred. Rendered with uml-mcp.

PlantUML source

@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
top to bottom direction
hide empty members
package "AudioTranscript" {
object "main.py" as FN0 {
  transcribe_audio_file()
  main()
}
}
@enduml

7.3. Public interface

Outside code can use everything listed here. The project also declares 0 public types.

Command line 1

main

Entry points

main.py entry file

7.4. Business logic

No classes were extracted, so these are the largest source files and their functions.

main.py: transcribe_audio_file, main
ai.py: No named functions.

7.5. External integrations

Hugging Face ai

7.6. Stack and dependencies

Python requirements.txt 5 runtime

Open the manifest

External dependencies

5 declared packages (5 runtime, 0 development) in requirements.txt.

Package table 5

External dependencies
Package	Version	Scope	Purpose	Registry
`SpeechRecognition`	—	runtime	Library for performing speech recognition, with support for several engines and APIs, online and offline.	pypi.org
`pydub`	—	runtime	Manipulate audio with an simple and easy high level interface	pypi.org
`rich`	—	runtime	Command line	pypi.org
`typer`	—	runtime	Command line	pypi.org
`boto3`	—	runtime	Cloud services	pypi.org

7.7. CI/CD pipeline

No CI/CD pipeline in the repository. The code is built and run by hand, as described above.

7.8. Deployment

Mermaid Deployment diagram

flowchart LR
  repo[("GitHub repository")]
  local["Local machine<br/>Python"]
  repo -->|"clone and run"| local

The repository has no Dockerfile, Compose file or hosting configuration, so the code runs on the machine that clones it.

7.9. Security

Environment variables 3

The page lists names without their values and underlines the ones that look like secrets.

AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_BUCKET_NAME

Nothing found for: Private interface, Services, Entities, Database, Monitoring, Testing.

8. Reference

4 / 4 eligible files read (6 in the tree); 0 oversized, 0 failed reads and 0 syntax diagnostics.

What the scan covers

Known dependency/build folders, credential files and binaries are excluded. The scan covers READMEs, recognized manifests and parser-supported source files.

Linguist statistics cover the whole repository and may include other languages.

10. Files to read 2

11. Glossary

Repository

The versioned source files, configuration, and history of a project.

README

The repository’s entry document, usually covering its purpose and initial setup.

Dependency

A library, tool, or service that another component needs to build or run.

CLI

A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.

12. References

antoinebou12. (2026, November 5). AudioTranscript. [Software repository] github.com.
antoinebou12. (2026, November 5). AudioTranscript: README. [Repository documentation] github.com.
antoinebou12. (2026, November 5). main.py. [Source file] github.com.
antoinebou12. (2026, November 5). requirements.txt. [Source file] github.com.
Boucher, A. (2026, October 23). AudioTranscript: From WAV chunks to transcription. [Project article] antoineboucher.info.

Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.