PT EN
Automation · Python

Papotech Editor

Podcast editing automation with Python

A command-line tool that automates the repetitive part of editing episodes of Papotech, the podcast of a university outreach project. It takes the recordings from two microphones and returns synced audio with long pauses shortened, a transcript and a list of spots to review.

View code on GitHub Listen to the podcast
Type
Command-line tool
Role
Sole developer
Context
Papotech university outreach podcast (in Portuguese)
Stack
Python · FFmpeg · Whisper

How it works

With mic1.wav and mic2.wav in the input folder, a single command (python main.py) runs the whole workflow:

  1. RecordingsLoads both microphones from the episode.
  2. SyncFinds the claps at the start and aligns the files.
  3. ProcessingShortens long pauses with identical cuts on both tracks.
  4. TranscriptionTranscribes with Whisper and flags spots to review.
  5. Output filesEdited WAVs, a reference mix and reports.

Problem and goal

The problem

Each episode is recorded with two microphones, into two separate files. Before any real editing could start, the files had to be aligned, long pauses had to be found and shortened, and the whole recording had to be listened to for speech mistakes — the same repetitive work on every single episode.

The goal

Cut down that manual work: automate syncing, pause trimming and finding speech mistakes, leaving only the final polish in CapCut to a human editor.

My role

I built the tool on my own, based on my own podcast editing routine: I mapped out the repetitive steps, wrote the pipeline in Python and organized the code into modules for syncing, cutting, transcription and reporting, with all settings centralized in config.py.

Technologies

  • Python
  • FFmpeg
  • Pydub
  • NumPy
  • SciPy
  • OpenAI Whisper
  • PyTorch

Features

  • Automatic syncing of both microphones based on hand claps.
  • Long-pause trimming, with identical cuts on both files.
  • Normalized reference mix to check the result.
  • Whisper transcription in Portuguese, with word-level timestamps.
  • Markers for repetitions, stutters and the “corta” (“cut”) cue spoken during recording.
  • Timestamps in CapCut's timeline, already offset by the intro jingle's length.
  • TXT, SRT and CSV reports, including the list of shortened pauses.
  • Final summary with the expected episode length and a warning if it falls under one hour.

Technical decisions

  • One command, separate stages. main.py only orchestrates; each stage lives in its own module (audio/, analysis/, reports/, utils/).
  • Settings in config.py. Thresholds, durations and paths change without touching the logic.
  • Fail early. If syncing isn't reliable, the program stops with a clear message instead of producing a broken episode.
  • The transcript flags, it doesn't cut. Speech mistakes become review markers; the decision to cut stays human.

Challenges and solutions

Challenge

Reliably detecting the claps

The claps are the sync reference, but the start of a recording also has speech, noise and other loud sounds.

Solution

RMS energy + peak detection

Only the first 20 seconds are analyzed. The audio is converted into RMS energy over windows of about 10 ms, peaks are found with scipy.signal.find_peaks, and the program picks the strongest pair spaced between 350 ms and 1.2 s apart.

Challenge

Never delivering out-of-sync audio

A wrong alignment ruins the whole episode, and it's hard to notice the error by listening to just one part.

Solution

Validate before cutting

If the gap between the claps differs by more than 150 ms between microphones, the process stops with an error message. Otherwise, the offset is calculated from the center of the clap pair, the claps are removed and both files are trimmed to the same length.

Challenge

Shortening pauses without choppy speech

Removing every silence makes the conversation sound unnatural, and a fixed threshold doesn't work for recordings with different volumes.

Solution

Adaptive threshold and center cuts

Only pauses longer than 2.5 s are changed. The silence threshold is derived from the recording's average loudness (dBFS − 18, clamped between −50 and −32 dBFS). The program removes only the middle of each pause and keeps 0.8 to 1.2 s, depending on its original length.

Challenge

Keeping both microphones aligned after cutting

If each microphone were cut based on its own audio, the files would drift out of sync again.

Solution

A single cut map

The cut map is calculated once, on the mix of both microphones, and applied identically to both files.

Challenge

Finding speech mistakes in a long episode

Listening to over an hour of audio to find repetitions and parts to cut is slow and tiring.

Solution

Normalized transcript + rules

The transcript is normalized (lowercase, no accents or punctuation) and matched against Portuguese correction phrases such as “corta” (“cut”) and “vou repetir” (“let me repeat that”). Repeated words and short phrases are flagged too, each with a 1.5 s margin before and after.

Verifiable results

  • Public code organized into modules in the project repository.
  • A complete eight-step pipeline that runs with a single command.
  • Eight output files ready for the final edit in CapCut: edited audio, a reference mix, a transcript, subtitles and reports.

What I learned

  • Hands-on audio processing: RMS energy, peak detection and dBFS thresholds.
  • Validating input and failing with a clear message instead of producing a wrong result.
  • Splitting code into modules with clear responsibilities and centralizing configuration.
  • Automating only what's repetitive and leaving creative decisions to a human editor.

What the tool produces

saida/
├── 01_MIC1_EDITADO.wav     # microphone 1 with the cuts applied
├── 02_MIC2_EDITADO.wav     # microphone 2 with the same cuts
├── 03_MIX_REFERENCIA.mp3   # mix for review
├── 04_transcricao.txt      # transcript
├── 05_transcricao.srt      # subtitles
├── 06_marcacoes.txt        # spots to review
├── 07_marcacoes.csv        # start and end in CapCut's timeline
└── 08_cortes_pausas.csv    # every shortened pause

Files written to the saida/ (output) folder, using the Portuguese names defined in the project's code.

Repository on GitHub Papotech Podcast