Stress refactor

[HatmanStack]

Summary by CodeRabbit

• New Features

  • Improved HLS streaming: append-only fade segments and tiered trailing pad for smoother voice-to-music transitions.

• Documentation

  • Added a comprehensive developer guide covering setup, architecture, API flow, code style, and CI details.

• Tests

  • Expanded unit tests covering fade segment behavior, offset calculations, error handling, and codec argument validation.

• Chores

  • CI workflow trigger updated to run on pull requests to main.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds CLAUDE.md documentation; introduces three HLS constants; refactors FFmpegAudioService HLS fade logic from rewriting to append-only fade segments and updates amix normalization; adds unit tests for the new fade behavior; changes CI trigger to run on pull_request.

Changes

Cohort / File(s)	Summary
Documentation CLAUDE.md	New repository guide for Claude Code usage: setup, architecture, frontend/backend breakdown, API flows, code style, and CI details.
HLS Configuration Constants backend/src/config/constants.py	Added HLS_TRAILING_PAD_BASE_SECONDS, HLS_TRAILING_PAD_PER_TIER, and HLS_FADE_DURATION_SECONDS to control trailing pad and fade duration for HLS streaming.
FFmpeg Audio Service backend/src/services/ffmpeg_audio_service.py	Refactored HLS fade workflow: renamed _apply_fade_to_segments → _append_fade_segments with new signature; streaming now emits segments without fades and appends fade segments later; applied tiered trailing pad calculation; FFmpeg amix now uses normalize=0; updated process_stream_to_hls and upload watcher logic.
Unit Tests (HLS Fade) backend/tests/unit/test_services.py	Added tests covering append-fade behavior: fade segment generation/upload, music-offset calculation, handling unknown music duration, FFmpeg failure handling, and explicit codec argument checks.
CI Workflow Trigger .github/workflows/ci.yml	Changed workflow trigger from push to pull_request targeting main.
Minor Import/Order Cleanups backend/src/handlers/lambda_handler.py, backend/src/handlers/middleware.py, backend/src/models/requests.py, backend/src/utils/circuit_breaker.py, backend/tests/unit/*	Small import-order or unused-import removals and one except-clause simplification; no behavioral changes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client
  participant FFmpegAudioService
  participant FFmpeg
  participant HLSStorage as HLS Storage
  participant HLSService

  Client->>FFmpegAudioService: start streaming job
  FFmpegAudioService->>FFmpeg: start streaming (no fade, amix normalize=0)
  FFmpeg->>HLSStorage: write HLS segments & playlist
  HLSStorage->>HLSService: notify/upload complete segments
  HLSService-->>FFmpegAudioService: upload watcher events

  note over FFmpegAudioService,HLSService: after streaming completes
  FFmpegAudioService->>FFmpeg: generate appended fade segments (using music offset, trailing pad)
  FFmpeg->>HLSStorage: upload fade segments & update playlist
  HLSStorage->>HLSService: publish updated playlist
  HLSService-->>Client: final playlist available

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• fix: code hygiene improvements for production readiness #10: Modifies ffmpeg_audio_service.py (logging around HLS/fade handling) and touches the same fade-related code paths refactored here.
• Hls update #7: Related "Hls update" changes to HLS workflow and fade method surface that overlap with this refactor.
• Refactor upgrade #1: Prior changes to ffmpeg_audio_service.py and config/constants.py affecting HLS/audio mixing and fade logic.

Poem

🐰 Hops the rabbit, ear held high,
Streams roll on beneath the sky.
Append a fade, a gentle tail,
Docs and tests keep every trail.
Hoppity-hop — the audio sails!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Stress refactor' is vague and generic, providing no meaningful information about the specific changes in the pull request, which involve HLS streaming fade behavior, FFmpeg audio service refactoring, and new configuration constants.	Replace with a more descriptive title that highlights the main change, such as 'Refactor HLS fade logic to append segments after streaming' or 'Update FFmpeg audio service for append-only fade segments.'

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch stress-refactor

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@backend/src/services/ffmpeg_audio_service.py`:
- Around line 580-583: The code calls
self.hls_service.upload_segment_from_file(...) and discards its boolean result,
then always appends seg_duration to segment_durations; instead check the
returned bool and handle failure the same way combine_voice_and_music_hls does
(e.g., if not upload_segment_from_file(...): raise/return an error) so failed
uploads are not counted in segment_durations and the playlist never references
missing segments; locate the call to upload_segment_from_file and the subsequent
segment_durations.append and add the conditional check and error handling around
it.

In `@backend/tests/unit/test_services.py`:
- Line 1148: The test's assertion expects a fade duration of 20s but the
implementation uses HLS_FADE_DURATION_SECONDS (10s); update the assertion in
backend/tests/unit/test_services.py to check for "afade=t=out:st=0:d=10" (or
interpolate HLS_FADE_DURATION_SECONDS) instead of "afade=t=out:st=0:d=20" so the
test aligns with _append_fade_segments and the HLS_FADE_DURATION_SECONDS
constant referenced by the code under test.

🧹 Nitpick comments (1)

CLAUDE.md (1)

38-43: Add a language specifier to the fenced code block.

The ASCII directory layout block has no language tag. Adding ```text satisfies markdownlint (MD040) and makes intent explicit.

Suggested fix

-```
+```text
 ├── frontend/    # Expo 52 / React Native 0.74 / TypeScript
 ├── backend/     # Python 3.13 / AWS Lambda / Pydantic
 ├── tests/       # Frontend test suites (Jest)
 └── docs/        # API.md, ARCHITECTURE.md
-```
+```