Buffle Audio Align

Fast vocal stack cleanup: find the timing offset, nudge the double, tame the consonants.

Buffle Audio Align is a JUCE audio plugin for vocal-stack alignment and articulation cleanup. Put it on a Dub or backing-vocal track, feed or monitor a Guide vocal, estimate the timing relationship, then tighten the Dub while preserving the small performance details that make stacked vocals feel alive.

Latest macOS preview: v0.4.0 for Standalone, VST3, and AU.

Current main continues the macOS preview with the current product surface: Phrase Health, Trust Meter reasons, Stack Role presets, Stack Spread Governor v0, Articulation Risk, Breath Preservation Mask v0, A/B preview modes, and copyable or saveable alignment reports. AU validation and strict VST3 pluginval evidence are recorded in docs/healthcheck-2026-07-07-au-validation.md and docs/healthcheck-2026-07-08-vst3-pluginval.md; the V1 release still needs clean-account install smoke, DAW latency matrix results, and Developer ID signing/notarization.

Links

• Landing page: https://buffleaudio-align.pages.dev/
• Latest preview release: https://github.com/iamknow0ne/buffleaudio_align/releases/tag/v0.4.0
• All releases: https://github.com/iamknow0ne/buffleaudio_align/releases
• Support Buffle Audio: https://buymeacoffee.com/hostin.tech
• Build notes: docs/build.md
• Deployment notes: docs/deployment.md
• Release inventory: docs/releases.md
• V1 tester guide: docs/v1-tester-guide.md
• Host latency validation: docs/validation-host-latency.md
• Healthcheck: docs/healthcheck-2026-07-08-v0.4.0-preview-package.md
• Roadmap: ROADMAP.md

Product Preview

The current app surface centers on Guide/Dub timing, Phrase Health, Trust Meter, Articulation Risk, Naturalness Guardrail, Stack Role presets, A/B audition, Consonant Tamer Lite, and report handoff.

Current landing capture: landing-product-2026-07-08.jpg.

Try Align

The public download is v0.4.0. It is a macOS preview, not the final V1 release.

1. Install or unzip the latest macOS preview from the GitHub release.
2. Open the Standalone app, or insert the VST3/AU on a Dub/double/backing-vocal track.
3. Route the Guide vocal into the sidechain when your DAW supports it.
4. Play the phrase and watch Guide/Dub confidence lock.
5. Read the signed offset and confidence-gated suggested nudge, including whether the Dub should move earlier or later.
6. Use manual Nudge, or the confidence-gated Apply Nudge workflow in the app UI.
7. Raise Consonant Tamer carefully to soften unmatched Dub attacks without crushing sustained vowels.
8. Watch the Articulation strip for suspected consonant clutter, then use Tamer mode to hear what the tamer is removing.
9. Switch Original, Aligned, All Diff, and Tamer to hear the dry Dub, processed preview, total changed material, or consonant-only material before trusting the move.
10. Try Stack Role presets when the layer is a tight double, natural choir, rap stack, or ADR-style dub.
11. Use Copy or Save Report to hand off phrase health, confidence, offset, suggested timing correction, changed-material stats, articulation risk, preview mode, role, and current controls.

Preview build note: v0.4.0 is useful for local testing, but it is not Developer ID notarized yet. Treat it as a macOS preview, not a broad public installer.

For structured testing, follow the V1 tester guide and paste the app's Copy Report output into feedback.

Current Product Capabilities

• Optional Guide sidechain input bus, with the main input treated as Dub.
• Live Guide/Dub monitoring, signed offset estimate, offset confidence, and bidirectional suggested nudge.
• Manual early/late nudge with host-latency compensation up to 120 ms in DAWs that support plugin delay compensation.
• Consonant Tamer Lite DSP plus Breath Preservation Mask v0 for soft sustained breath-like material and Guide-matched attacks.
• First Articulation Risk strip for suspected unmatched Dub attacks. This is a visual aid over current transient/tamer evidence, not full phoneme detection.
• Original / Aligned / All Diff / Tamer preview modes for A/B trust checks and consonant-only removed-material audition.
• Stack Role presets tune the feel for doubles, choirs, rap stacks, and ADR, including Naturalness, Consonant Tamer, Guide Blend, and Stereo Focus targets.
• Stack Spread Governor v0 uses Stereo Focus to narrow tight doubles/rap stacks or preserve wider choir/ADR layers with a lightweight mid/side width stage.
• Phrase Health classifier for route/listen/safe-nudge/print-ready/check-naturalness/check-articulation/changed-material/too-much states, backed by stable Trust Meter reason codes.
• Session-flow rail and Next Best Move card that tell testers what to do next instead of exposing fake capture/analyze certainty.
• Changed-material meter now separates broad processed-vs-original preview change from tamer-only consonant removal.
• Naturalness Risk Guardrail v0: a UI/report policy layer that flags Natural, Check Diff, or Too Much based on changed material, nudge, tamer, tightness, naturalness, and stack role.
• Copy and Save Report handoff summary for Phrase Health, Phrase advice, Trust Meter reason/advice, confidence, offset, suggested timing correction, all-change and tamer-only removed-material amounts, articulation risk, preview mode, stack role, and current controls.

Build And Release Capabilities

• Branded Buffle Audio editor with the shared logo, dark teal visual identity, and in-plugin About panel.
• Persistent JUCE parameters through AudioProcessorValueTreeState.
• Session state save/restore.
• Standalone DSP library with unit tests for envelope extraction, global offset estimation, manual nudge timing, preview-mode rendering, changed-material metering, stack-role profiles, and consonant-tamer behavior.
• CMake build for Standalone, VST3, and AU.
• Local macOS .pkg installer generation.
• Static landing page in landing/, deployed to Cloudflare Pages and safe to expose without serving the full repository.

Product Shape

Buffle Audio Align is positioned as a timing decision surface for vocal doubles, not a black-box warper. Align helps you:

1. Monitor or capture Guide and Dub.
2. Estimate the signed timing relationship without showing fake certainty on weak material.
3. Preview or apply a confidence-gated early/late timing nudge.
4. Add vocal-stack-specific consonant cleanup while protecting soft breath-like material.
5. A/B Original, Aligned, All Diff, and Tamer preview before trusting or printing the move in the host.
6. Read changed-material meters for broad processed-vs-original change and consonant-only tamer removal.
7. Use the Articulation Risk strip as a warning for likely Dub consonant clutter, then confirm with Tamer audition.
8. Apply role-aware stack presets for doubles, harmony stacks, rap layers, and ADR-style dubs.
9. Use Stereo Focus to keep tight roles centered or let looser roles breathe wider.
10. Copy or save an alignment report for tester/session handoff.

Guide Fallback Intelligence

Align never pretends a missing Guide is a confident read. When the sidechain is absent, weak, or ambiguous, the Trust Meter explains why timing is unavailable and gives the next routing/listening action instead of showing fake precision.

Trust Meter reason codes:

• ROUTE_GUIDE: no usable Guide sidechain detected. Route the lead vocal into the Guide input and play the phrase again.
• GUIDE_TOO_QUIET: Guide exists but is below the usable signal floor.
• DUB_TOO_QUIET: Dub/main input is too quiet for nudge, tamer, or report decisions.
• LISTENING_FOR_CONFIDENCE: Guide and Dub are present, but the timing match is not stable enough yet.
• LOCKED_NO_NUDGE: timing is stable and no useful nudge is needed.
• DUB_EARLY_SAFE_DELAY: Dub is early; a confidence-gated delay is available.
• DUB_LATE_SAFE_ADVANCE: Dub is late; a confidence-gated advance is available.

V1 Direction

The V1 wedge is transparent stack cleanup: delay-safe nudge + trust meter + consonant control.

Differentiating V1 feature candidates:

• Trust Meter Alignment: explain Guide source, Guide/Dub levels, offset direction, confidence, and the reason a nudge is available or blocked.
• One-Click Safe Nudge: apply only confidence-gated early/late corrections, with clear unavailable states for weak, ambiguous, or unsafe material.
• Consonant Collision Detector: highlight likely doubled consonant flams against the guide. Initial Articulation Risk strip is implemented; full phoneme-aware detection remains future work.
• Consonant Tamer Lite: reduce unmatched Dub consonant bursts without flattening sustained vowels.
• Removed Material Audition: use All Diff for the full preview delta and Tamer for consonant-only material reduced by Consonant Tamer.
• Naturalness Guardrail: warn when timing correction risks sterile doubles. Initial Natural / Check Diff / Too Much policy layer is implemented.
• Guide Fallback Intelligence: make routing problems visible and actionable. Initial Trust Meter reason codes are implemented.
• Phrase Health Report: classify routing/listening, safe nudge, print-ready, changed material, naturalness, articulation, and too-much-cleanup states. Initial classifier is implemented.
• Stack Spread Governor: preserve controlled width across doubles/harmonies. Initial Stereo Focus mid/side governor is implemented.
• Breath Preservation Mask: protect breaths and expressive attacks. Initial soft sustained material protection is implemented inside Consonant Tamer.
• Vowel-Only Warp Preview: future micro-warping that avoids consonant smearing.
• Harmony-Aware Tightness Presets: Double Tight, Choir Natural, Rap Stack, and ADR Loose roles tune tightness, naturalness, consonant amount, guide blend, and stereo focus.
• Exportable Alignment Report: copy or save phrase offset, confidence, nudge, changed-material stats, articulation risk, and current controls for session handoff.

See ROADMAP.md for milestones, risks, and verification gates.

Build

The canonical build path is CMake. It currently uses the local JUCE checkout at:

/Users/hostin/vibecoding/waveform-visualizer/JUCE

Override it with JUCE_PATH=/path/to/JUCE.

The project version is read from VERSION. Release scripts use that file unless VERSION=x.y.z is provided in the environment.

cmake -S . -B build/cmake-debug \
  -DJUCE_PATH=/Users/hostin/vibecoding/waveform-visualizer/JUCE \
  -DCMAKE_BUILD_TYPE=Debug \
  -DBUFFLE_BUILD_TESTS=ON

cmake --build build/cmake-debug --config Debug --parallel
ctest --test-dir build/cmake-debug --output-on-failure

For a repeatable local V1 evidence pass, run:

scripts/v1_local_preflight.sh
scripts/v1_local_preflight.sh --package

Package

scripts/build_and_package_macos.sh

Outputs:

• dist/stage/Buffle Audio Align.app
• dist/stage/Buffle Audio Align.vst3
• dist/stage/Buffle Audio Align.component
• dist/BuffleAudioAlign-${VERSION}-macOS.pkg
• dist/BuffleAudioAlign-${VERSION}-macOS-bundles.zip

The staged bundles are ad-hoc signed for local verification. The package payload hygiene gate removes AppleDouble/.DS_Store entries before verification, but the package is not Developer ID Installer signed or notarized yet.

Landing Page

Cloudflare Pages production URL:

https://buffleaudio-align.pages.dev/

Serve only the landing page folder locally:

scripts/serve_landing.sh

Then open:

http://127.0.0.1:8088

If that port is already busy:

PORT=8099 scripts/serve_landing.sh

Expose only the landing folder through a quick Cloudflare Tunnel:

scripts/expose_landing_cloudflared.sh

Deploy the landing folder to Cloudflare Pages:

npx wrangler@latest pages deploy landing --project-name=buffleaudio-align --branch=main

GitHub Releases

Both public preview releases are published on GitHub:

• v0.4.0: latest macOS bundle archive plus testable .pkg preview.
• v0.3.0: historical macOS bundle archive plus testable .pkg preview.
• v0.2.0: macOS bundle archive plus testable .pkg preview.

For current testers, prefer the bundle archive. The .pkg is available for testing, but it is not Developer ID signed or notarized yet.

To publish a future release after building:

RELEASE_MODE=zip GITHUB_REPO=iamknow0ne/buffleaudio_align scripts/publish_github_release.sh

RELEASE_MODE=zip publishes the preferred preview archive. RELEASE_MODE=full requires both the clean bundle archive and clean .pkg installer. New releases are draft prereleases by default until V1 gates pass.

Source Layout

BufflePlug-Analyzer/Source/
  DSP/
    ConsonantTamer.*
    AlignmentReport.*
    BidirectionalNudge.*
    EnvelopeFeatureExtractor.*
    ManualNudgeDelay.*
    NaturalnessGuardrail.*
    PreviewModeMixer.*
    RemovedMaterialMeter.*
    StackRolePreset.*
    TimingOffsetEstimator.*
    TrustDiagnostics.*
  PluginProcessor.*
  PluginEditor.*

tests/
  DSPCoreTests.cpp

landing/
  index.html
  styles.css
  assets/

scripts/
  build_and_package_macos.sh
  expose_landing_cloudflared.sh
  publish_github_release.sh
  serve_landing.sh

Known Gaps

• Developer ID signing and notarization are still needed before broader distribution.
• JUCE should be pinned or vendored for fully reproducible builds.
• The legacy generated Xcode project should be regenerated if it becomes part of the supported build path.
• The current alignment path is nudge/analysis-first; full DTW/warping remains a future milestone.