One-File Binaural Studio: Full Build Prompt and Guide

TL;DR

This post gives you a copy-paste master prompt that makes any competent AI generate a single, production-quality HTML file for a complete binaural beats app. You get Web Audio precision, safety caps, presets, guided sessions, accessibility, offline caching, deep links, and JSON import or export. Paste the prompt, run once, save the output as binaural-studio.html, and open it in a modern browser.

Intro

Binaural apps often ship with risky volumes, jittery tuning, or flaky offline behavior. This prompt solves that by forcing a one-file, no-dependency build with strict gain limits, smooth ramps, and accessible controls. The result is a clean HTML page that uses the Web Audio API, runs offline, and includes safety and UX guardrails. It is not medical advice. Use headphones, start low, and stay within your comfort.

What this prompt does

• Instructs an AI to return one self-contained HTML file with inline CSS and JavaScript only.
• Builds sine-tone carriers per ear with safe gain caps, click-free ramps, soft limiting, and visual meters.
• Adds presets, custom or derived frequencies, session timer with fade, guided JSON timelines, tap tempo, breathing pacer, and optional voice prompts.
• Provides offline operation with a minimal service worker and a data URL manifest.
• Enforces accessibility: semantic HTML, ARIA live updates, high contrast, keyboard shortcuts, reduced motion.
• Persists settings, supports deep links, and imports or exports JSON.

How to use

1. Copy the full prompt below.
2. Paste it into your AI tool as a single message.
3. The expected output is one complete .html file. Save it as binaural-studio.html.
4. Open it in a modern browser. No install. No internet required after first load.
5. Verify acceptance tests in the prompt. If you want tweaks, ask the AI to regenerate using the same prompt and specify edits.

The Custom Prompt

ROLE AND OUTPUT
Act as a senior Web Audio engineer and front-end designer. Produce one self-contained HTML file with embedded CSS and JavaScript. No external libraries, fonts, or images. No network calls. The file must run locally and offline.

AUTHORING RULES
- Write clean, readable, commented code.
- Separate concerns inside a single file using <style> and <script>.
- Use semantic HTML, accessible labels, and ARIA where needed.
- Never exceed a hard 70 percent output gain. Implement soft limiting.
- Implement smooth, click-free ramps on all audio changes.
- Return only the final HTML code. No explanations outside of code comments.

OBJECTIVE
Build a production-quality binaural beats web application that allows custom and preset carrier frequencies, safe playback, session timing, visual meters, accessibility features, and offline operation.

CORE FEATURES
1) Custom Frequencies
   - Numeric inputs for left and right carrier frequencies, 20 to 1000 Hz.
   - Step 0.1 Hz. Clamp and validate. Inline error hints.
   - Beat-by-difference mode: user sets a base carrier and a target beat frequency, app derives the other channel. Toggle which side is derived.

2) Presets
   - Built-in: Deep Focus 200/210, Creative Flow 180/188, Mental Alertness 200/220, Study Mode 160/172.
   - Add: Relaxed Alpha 220/230, Calm Theta 150/156, Morning Beta 240/248.
   - Crossfade when switching presets with a 1 to 5 second morph.

3) Audio Controls
   - Play and Pause primary toggle. Mute toggle.
   - Volume slider capped at 0.7 gain. Enforce in code.
   - Keyboard shortcuts: Space toggles play or pause, M toggles mute, ArrowUp and ArrowDown adjust volume by 5 percent, Left and Right arrows nudge selected frequency, Shift multiplies precision to 0.1 Hz, Alt multiplies precision to 0.01 Hz.

4) Display and Feedback
   - Live readout: Left Hz, Right Hz, Beat Frequency.
   - Qualitative band label based on beat: Delta, Theta, Alpha, Beta, Gamma, or Out of Range.
   - Small stereo monitor that flashes L and R while running.
   - One-tap left and right sanity test pings.

5) Session Timer
   - Start, Pause, Reset. Default 15 minutes. Configurable.
   - Auto fade out 2 seconds at end, then stop.
   - Optional end chime generated in code at low volume.

6) Guided Sessions and Scheduling
   - Session scripting via a compact JSON timeline with timestamp seconds and optional fade seconds. Example:
     [
       {"t":0,   "l":200, "r":210, "fade":1.0},
       {"t":600, "l":208, "r":216, "fade":2.0},
       {"t":1200,"stop":true, "fade":3.0}
     ]
   - Tap tempo and BPM sync. Map beat frequency to subdivisions.
   - Breathing pacer ring that expands and contracts on a user cycle. Sync with timer.
   - Optional offline voice prompts using SpeechSynthesis for milestones. Respect mute and duck other audio.

TECHNICAL DESIGN
Audio Graph
- Create AudioContext on first user gesture. latencyHint "interactive" if available.
- Two OscillatorNode sources generating sine waves, one per ear.
- Each oscillator goes through its own StereoPannerNode, set to −1 for left and +1 for right.
- Merge to a shared GainNode (master volume), then to a DynamicsCompressorNode (soft limiter), then to destination.
- Optional modules:
  - Equal-loudness compensation: BiquadFilterNode low-shelf that tracks a simple curve at low volumes.
  - Noise blender: pink or brown noise generated procedurally. Prefer AudioWorklet, fall back to a BufferSource when not supported.
  - Light reverb: small generated impulse or simple Schroeder network built with DelayNode and GainNode.
  - Global balance trim: post-mix StereoPannerNode to re-center without breaking binaural separation.

Smooth Retune and Fades
- On any frequency or mode change, schedule linear ramps to avoid clicks.
- Implement start and stop with 250 ms minimum fade in and out. Longer fades for timer end and preset crossfades.

Analyser and Metering
- AnalyserNode for oscilloscope and spectrum display. Render at 30 fps desktop, 20 fps on battery saver.
- Health dashboard: RMS and peak bars, and gain reduction indicator from the compressor.
- True-peak proxy: simple oversample estimate for visual metering only.

Lifecycle and Cleanup
- Handle suspended contexts, especially on iOS. Call resume after user gesture.
- Retune in place when possible. On teardown, stop oscillators, disconnect nodes, and close context.
- Before unload, stop audio cleanly.

SAFETY AND UX GUARDRAILS
- Hard cap master gain at 0.7. Keep compressor connected. Prevent clipping.
- Exposure guard: track cumulative listening minutes per day in localStorage and warn on user-set limits.
- Safe preset validator: block values outside 20 to 1000 Hz or beat over 40 Hz. Warn if left equals right.
- Prominent guidance text: Use stereo headphones. Start at low volume. Typical sessions 15 to 30 minutes.
- Health disclaimer modal presented once. Store acknowledgement locally.
- Left and Right test pings and instruction to swap headphones if channels feel reversed.

ACCESSIBILITY
- Semantic HTML and labels bound to inputs. Descriptive titles on controls.
- Visible focus outlines and high contrast. Respect prefers-reduced-motion to disable animated gradients and heavy transitions.
- Announce status changes and timer milestones through aria-live.
- Full keyboard control for all essential actions.

INTERNATIONALIZATION
- Simple key-value i18n dictionary and language dropdown. Persist choice. Provide English and Spanish strings to start.

PERSISTENCE AND SHARING
- Save last settings in localStorage. Store a version key for safe migration.
- Deep links via URL parameters, for example ?l=200&r=210&vol=0.5&p=Deep%20Focus&beatMode=on.
- Export and import configuration to JSON. Copy and restore from clipboard.
- Web Share API hook on mobile where supported.

OFFLINE AND PWA-LITE
- Must work offline as a plain file.
- Register a minimal service worker using a Blob URL to cache the single page for repeat visits.
- Add a small manifest via a data URL so install prompts can work while still shipping one file.

UI AND VISUAL DESIGN
- Modern dark theme with purple and blue gradient background.
- Glassmorphism panels with translucency, blur, and soft shadows. Rounded corners, subtle hover and press animations.
- Responsive layout: single column on phones, two-panel on larger screens. No horizontal scroll. Touch targets at least 44 by 44 pixels.
- Clear state feedback for Play, Pause, Mute, and active preset.
- Small “How it works” panel that explains carriers and beat frequency in one paragraph.

CONTENT LABELS
- Beat band ranges and labels:
  - Delta 0.5 to 4 Hz, Theta 4 to 8 Hz, Alpha 8 to 13 Hz, Beta 13 to 30 Hz, Gamma 30 to 40 Hz.
  - Show neutral, non-medical descriptions.

CONTROLS AND INTERACTION EXTRAS
- Fine control modes: Shift for 0.1 Hz steps, Alt for 0.01 Hz, long-press on mobile opens numeric keypad sheet.
- A and B compare slots to store two settings. Instant crossfade that never exceeds the cap.
- Global balance trim separate from per-oscillator pan.

PERFORMANCE AND COMPATIBILITY
- Prefer AudioWorklet for noise and metering. Fall back cleanly when unsupported.
- Display sample rate. Use double precision for frequency math.
- Battery saver mode reduces analyser resolution and animation frame rate when backgrounded or on low power.

DIAGNOSTICS AND QA
- Self-test panel verifies node graph connections, compressor presence, channel pan values, and ramp scheduling. Report results inline and in console assertions.
- Error toasts for context suspend, resume failures, or permission problems.
- Show a compact loading state during first play initialization.

BPM AND BREATHING UTILITIES
- Tap tempo input. Map beat frequency to BPM subdivisions.
- Breathing pacer ring. User can set inhale, hold, and exhale durations. Sync with timer.

COPY AND SHARE
- Shareable URL builder that includes current controls and timeline. Respect clamping on import.

BANDWIDTH AND PRIVACY
- No analytics, no external requests, no telemetry. Everything local to the browser.

ACCEPTANCE CRITERIA
1) Single HTML file, runs locally and offline with service worker cache and manifest via data URL.
2) Setting 200 Hz left and 210 Hz right shows a 10 Hz beat and Alpha label.
3) Volume never exceeds 0.7 master gain. Compressor connected and shows gain reduction on overload test.
4) All starts, stops, mutes, preset changes, and retunes are click-free with scheduled ramps.
5) Timer ends with a two-second fade out, then stops. Optional end chime plays at low volume.
6) Presets, deep links, JSON import and export, and localStorage persistence all work.
7) Keyboard shortcuts function. App usable without a mouse. Screen reader announces key status changes.
8) Reduced motion mode removes nonessential animations. Contrast passes WCAG AA.
9) Session scripting executes on schedule with fades, and continues correctly after tab backgrounding.
10) A and B compare crossfades without overshoot. Global balance trim recenters image without altering beat math.
11) Analyser scope renders at 30 fps on desktop and 20 fps on mobile battery saver. Performance degrades gracefully.
12) Calibration wizard stores per-channel trims and applies them on every play.
13) Exposure guard tracks minutes per day and surfaces a friendly warning when limits are exceeded.
14) Self-test panel passes. Console shows no uncaught errors or unhandled promise rejections.
15) All UI guidance and safety messages are visible on phones and desktops.

DELIVERABLE FORMAT
Return only the complete HTML file that implements everything above. Include <!doctype html>, a <style> block for theme and layout, and a <script> block for all logic. No external files, fonts, images, or frameworks.

Step by step usage

1. Paste the prompt into your AI model and run.
2. Save the single response as binaural-studio.html.
3. Open the file in Chrome, Edge, Firefox, or Safari.
4. Put on stereo headphones. Set volume low.
5. Pick a preset. Verify beat label and left or right panner.
6. Set a session timer. Press Play.
7. Optional. Load a JSON timeline or tap tempo.
8. Export your config as JSON for future sessions.

Applied example

Goal. A 15 minute focus session that starts at Alpha 10 Hz then glides to Beta 16 Hz.
Steps.

• Start with preset Deep Focus (200 or 210).
• Load this session script in the app timeline input.

[
  {"t":0,   "l":200, "r":210, "fade":1.5},
  {"t":300, "l":204, "r":220, "fade":2.0},
  {"t":600, "l":208, "r":224, "fade":2.0},
  {"t":900, "l":212, "r":228, "fade":2.0},
  {"t":1200,"stop":true, "fade":3.0}
]

• Timer 900 seconds. End chime on.
• Keyboard. Space toggles play or pause. ArrowUp raises volume 5 percent.
• Acceptance check. Beat label should move from Alpha to low Beta during the session and fade out at the end.

Notes on safety and accessibility

• Master gain never exceeds 0.7. The compressor should show a little gain reduction on loud test tones.
• Page Visibility pauses ramps on background tabs and resumes safely.
• Reduced Motion removes heavy gradients and slows nonessential animations.
• Health disclaimer appears once. Acknowledge to continue.

References and links

• MDN. Web Audio API : overview of audio nodes, timing, and routing.
• MDN. DynamicsCompressorNode : soft limiting to prevent clipping.
• MDN. BiquadFilterNode : low-shelf and other filters for EQ compensation.
• MDN. AudioWorklet : custom audio processing for noise or metering.
• MDN. Service Workers : offline caching for repeat visits.
• MDN. Web App Manifest : install prompts via data URL.
• MDN. SpeechSynthesis : optional offline voice prompts.
• MDN. Page Visibility API : auto-pause on tab blur.
• W3C. WCAG 2.1 : contrast and motion guidance.

Conclusion

You now have a drop-in prompt that manufactures a safe, accessible, offline binaural studio in one file. It builds a reliable audio graph with soft limiting, smooth retunes, guided timelines, and strong UX defaults. Paste, run, save, and verify with the acceptance criteria. Iterate only if you need custom visuals or extra presets.