audio-ring-buffer

name	audio-ring-buffer
description	Maintain a rolling microphone audio buffer and export/send the last N minutes on request. Use when the user asks for features like "save last 15 minutes", "send last X minutes", start/stop always-on room recording, or audio ring-buffer troubleshooting on this Pi.

Audio Ring Buffer Skill

Use the bundled scripts in scripts/ for deterministic behavior.

Default device

This setup uses ALSA device:

• plughw:2,0

Commands

Run from skill directory:

• Start recorder: scripts/start_buffer.sh
• Stop recorder: scripts/stop_buffer.sh
• Status: scripts/status_buffer.sh
• Export last 15 minutes: scripts/export_last_minutes.sh 15
• Export last N seconds: scripts/export_last_seconds.sh 30
• Prepare sendable export (+ optional label-based filename rewrite): scripts/prepare_send_audio.sh --minutes 5 --label "my take"
• Export/send last detected song window: scripts/prepare_send_audio.sh --song --label "Song Title"
• Purge buffer files (safe): scripts/purge_buffer.sh --yes
• Parse natural-language send request: scripts/parse_audio_request.sh "<request text>"

Natural-language request handling (minutes + optional label)

When user asks for buffered audio, parse both minute count and optional caption label.

Use:

• scripts/parse_audio_request.sh "<request text>"

Output format:

• mode=window|song
• minutes=<N>
• label=<text or empty>

Rules:

1. Minute parsing:
   • Match phrases like "last 15 minutes", "past 10 mins", "send last hour"
   • If a number is present, use it as <N>
   • If no number is present, default to 15
   • Clamp to 1..120
2. Song-mode parsing:
   • If request includes last song, set mode=song.
   • Support title phrasing like as <title>.
   • Example: send me the last song as Bigger Than My Body.
3. Label parsing (optional):
   • Accept natural phrasing with keywords like label, title, description, caption, called, named, as
   • Examples:
     • send me last 3 minutes with label "Take 4 chorus"
     • send last minute, title: Basement idea
     • send last 5 minutes called Rick test
     • send me the last song as No Such Thing
4. Export audio with parsed mode:
   • Window mode: scripts/export_last_minutes.sh <N>
   • Song mode: scripts/prepare_send_audio.sh --song [--label ...]
5. Caption/body text when sending:
   • Always append audio status to outgoing caption/body:
     • (clipped) first=<MM:SS.mmm> clipped=<X.XX%> when clipping is detected
     • (loud) when not clipped and 70th-percentile loudness reaches threshold
     • (soft) when not clipped and threshold is not reached
   • If label is present: caption starts with label text
   • If label is empty: use default body (Here’s the last <N> minutes/seconds of buffered audio.)
6. Filename rewrite when label is present:
   • Replace the initial filename segment (last-30s, last-5m, last-song, etc.) with kebab-case label text.
   • Example: label potato tomato + 10s export → potato-tomato-YYYYMMDD-HHMMSS.m4a
7. Song boundary detection:
   • Uses scripts/find_last_song_window.py over recent buffered audio.
   • Finds the last >=10s quiet run (nothing playing) and sets song start at the end of that run.
   • Export includes an extra 2s pre-roll silence/context at the beginning (start - 2s, clamped to 0).
8. Clipping analysis:
   • scripts/report_clipping.sh <audio-file> for human-readable status
   • scripts/report_clipping.sh <audio-file> --json for structured output
   • Analysis ignores first 500 ms for detection math, but reported clip time stays relative to file start.

Sending audio to user

Default destination for "send me" audio requests is Telegram.

1. Run export script to generate file path.
2. Use message tool (not shell curl) with:
   • channel=telegram
   • target=8456685608
   • filePath=<exported file>
3. Keep response concise and include the duration exported.
4. Only use another channel if the user explicitly asks for a different destination.

Purge safety + confirmation

• Always ask for explicit confirmation before any purge request.
• Use scripts/purge_buffer.sh --yes only after user confirms.
• Purge now performs a safe sequence when recorder is running: stop recorder → purge files → restart recorder.

Notes

• Recorder writes 20s WAV chunks and prunes old files (5-minute ring buffer, ~6-minute keep window).
• Export uses ffmpeg concat to produce one m4a file.
• If ffmpeg is missing, install it or switch exporter to WAV pass-through.