<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[SagaFlow Engineering]]></title><description><![CDATA[SagaFlow Engineering]]></description><link>https://sagaflow.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Sun, 22 Nov 2026 14:55:09 GMT</lastBuildDate><atom:link href="https://sagaflow.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Your mute button does nothing on iPhone, and the feature check says it works]]></title><description><![CDATA[On iOS you can set audio.volume and read it back, but the sound never changes, and the usual feature probe says it works. How we fixed mute.]]></description><link>https://sagaflow.hashnode.dev/your-mute-button-does-nothing-on-iphone-and-the-feature-check-says-it-works</link><guid isPermaLink="true">https://sagaflow.hashnode.dev/your-mute-button-does-nothing-on-iphone-and-the-feature-check-says-it-works</guid><category><![CDATA[safari]]></category><category><![CDATA[JavaScript]]></category><category><![CDATA[iOS]]></category><category><![CDATA[Web Development]]></category><dc:creator><![CDATA[SagaFlow]]></dc:creator><pubDate>Wed, 11 Nov 2026 23:04:31 GMT</pubDate><content:encoded><![CDATA[<p>SagaFlow is a browser story game: an AI narrator writes each scene while background music plays, the narration is read aloud, and there is a radio page with its own player. That makes three separate audio lanes, all built on plain <code>&lt;audio&gt;</code> elements, and all three had the same bug on iPhone: the mute button did nothing.</p>
<p>We fixed it once, shipped the fix, and the bug was reported again three weeks later on a real iPhone. The second fix is the one in production now. This post is about why the first one never ran.</p>
<h2>iOS ignores <code>volume</code></h2>
<p>On iOS and iPadOS, writing to <code>HTMLMediaElement.volume</code> does not change what the listener hears. Apple keeps loudness for the hardware buttons. This applies to every browser on the platform, because Chrome, Firefox and Edge on an iPhone all run on WebKit.</p>
<p>So the usual way to fade music out:</p>
<pre><code class="language-ts">function fadeOut(audio: HTMLAudioElement, ms = 400) {
  const start = performance.now();
  const from = audio.volume;
  const tick = (now: number) =&gt; {
    const t = Math.min(1, (now - start) / ms);
    audio.volume = from * (1 - t);
    if (t &lt; 1) requestAnimationFrame(tick);
  };
  requestAnimationFrame(tick);
}
</code></pre>
<p>runs to completion on an iPhone, sets <code>volume</code> to 0, and the track keeps playing at full loudness. Only two things actually silence an element there: <code>muted = true</code> and <code>pause()</code>.</p>
<h2>The first fix: feature-detect it</h2>
<p>The textbook answer is not to sniff the platform but to probe the feature. Write a value, read it back, and see if it stuck:</p>
<pre><code class="language-ts">function canControlVolume(): boolean {
  const probe = document.createElement('audio');
  probe.volume = 0.5;
  return Math.abs(probe.volume - 0.5) &lt; 0.01;
}
</code></pre>
<p>We wrote that, routed mute through <code>muted</code> whenever the probe said no, and swapped the volume slider for a plain mute toggle. It worked in every test we could run on a desktop browser. On a real iPhone it never engaged.</p>
<h2>Why the probe lies</h2>
<p>Older iOS versions let the written value revert on the next tick, so a write-then-read probe used to catch them. Current WebKit accepts the write and reads the same value straight back, while the output stays at full loudness. The probe returns a confident "yes, volume works" on exactly the platform it was written for, so our iOS branch was dead code.</p>
<p>We are not the first to hit this. video.js special-cases iOS in its own volume check for the same reason.</p>
<h2>The fix that shipped: ask about the platform</h2>
<p>This is one of the few cases where platform detection is the honest answer, because the behaviour is a platform policy, not a missing API:</p>
<pre><code class="language-ts">export function isAppleTouchDevice(): boolean {
  if (typeof navigator === 'undefined') return false;
  const ua = navigator.userAgent || '';
  if (/iPad|iPhone|iPod/i.test(ua)) return true;
  // iPadOS 13+ reports itself as "Macintosh". No Mac has a touchscreen,
  // so a touch-capable Mac user agent is an iPad in desktop mode.
  return /Mac/i.test(ua) &amp;&amp; navigator.maxTouchPoints &gt; 1;
}

let cached: boolean | null = null;

export function canControlAudioVolume(): boolean {
  if (cached != null) return cached;
  if (isAppleTouchDevice()) return (cached = false);
  // Everywhere else the probe is still useful: some locked-down webviews and
  // TV browsers ignore volume writes too, and they don't announce themselves.
  try {
    const probe = document.createElement('audio');
    probe.volume = 0.5;
    return (cached = Math.abs(probe.volume - 0.5) &lt; 0.01);
  } catch {
    return (cached = true);
  }
}
</code></pre>
<p>The iPad line matters: an iPad in its default desktop-class browsing mode sends a Mac user agent, so a check for "iPad" alone misses most iPads.</p>
<h2>Rules the rest of the code follows</h2>
<p>The check is only half of it. Every caller follows three rules:</p>
<ol>
<li><strong>Silence is never <code>volume = 0</code>.</strong> Mute goes through <code>muted</code> (or <code>pause()</code>), and unmute clears <code>muted</code> before calling <code>play()</code>. On desktop we still fade, then set <code>muted</code> at the end anyway, so if some platform starts ignoring volume again, mute still works.</li>
<li><strong>No slider where it can't work.</strong> When <code>canControlAudioVolume()</code> is false, the volume control becomes a plain mute toggle. A slider that moves and changes nothing is worse than no slider.</li>
<li><strong>Don't trust <code>requestAnimationFrame</code> to finish a fade.</strong> When the page stops painting (a backgrounded tab, a covered window), rAF stops too, but audio keeps playing. A fade waiting on rAF could leave the track audible indefinitely. We set <code>muted</code> again on a plain <code>setTimeout</code> just after the fade's duration:</li>
</ol>
<pre><code class="language-ts">fadeAudioVolume({ audio, toVolume: 0, durationMs: 400, onComplete: () =&gt; { audio.muted = true; } });
setTimeout(() =&gt; { audio.muted = true; }, 400 + 100);
</code></pre>
<h2>What about Web Audio?</h2>
<p>A <code>GainNode</code> does control loudness on iOS, and it's the standard answer when you need real volume levels there. It needs the media routed through <code>createMediaElementSource</code>, and for cross-origin audio that only produces sound if the file is served with CORS headers. Our audio comes from a CDN that doesn't send them, so a gain node would have produced silence. On iOS we accept two states, on and off, and the hardware buttons do the rest.</p>
<h2>Testing it without an iPhone</h2>
<p>Because the detection doesn't probe any more, you can't fake iOS by patching <code>HTMLMediaElement.prototype.volume</code> in a desktop browser. We added a QA switch instead, read once per page load:</p>
<pre><code class="language-ts">// localStorage.qa_audio_volume_locked = '1'  -&gt; behave like iOS (mute-only)
// localStorage.qa_audio_volume_locked = '0'  -&gt; force normal volume control
</code></pre>
<p>It lets us check the mute-only UI and the <code>muted</code> paths in a desktop browser. It doesn't replace a real device: the bug that started all this passed every desktop check we had.</p>
<h2>Takeaways</h2>
<ul>
<li>On iOS, <code>volume</code> can be written and read back, and none of it changes the sound. Use <code>muted</code> and <code>pause()</code>.</li>
<li>A feature probe is only as good as the platform's honesty. When a platform accepts a value and ignores it, detect the platform.</li>
<li>Remember iPads in desktop mode: check for a Mac user agent with touch support.</li>
<li>Test audio on real devices. Emulators and desktop browsers reproduce the API, not the speaker.</li>
</ul>
<hr />
<p><em>SagaFlow (<a href="https://sagaflow.ai/?utm_source=hashnode&amp;utm_medium=article&amp;utm_campaign=ios-volume">sagaflow.ai</a>) is built by a small team that has spent the past year writing it by hand, from the React front end to the prompt-flow engine that runs each scene. This post was written by the AI coding assistant our team works with, from the code and commit history of the fix; the fix itself has been in production since September 2026.</em></p>
]]></content:encoded></item></channel></rss>