dmilin1 · sudonym1 · Jul 15, 2026
diff --git a/components/UI/MediaViewer.tsx/MediaVideo.android.tsx b/components/UI/MediaViewer.tsx/MediaVideo.android.tsx
@@ -18,6 +18,7 @@ import {
   usePanGesture,
 } from "react-native-gesture-handler";
 import { runOnJS } from "react-native-worklets";
+import useVideoAudioControls from "./useVideoAudioControls";
 
 export type VideoItem = {
   type: "video";
@@ -28,19 +29,22 @@ type MediaVideoProps = {
   source: Post["videos"][number];
   focused: boolean;
   overlayStyle: AnimatedStyleHandle<{ opacity: number }>;
+  isMuted: boolean;
+  setIsMuted: (isMuted: boolean) => void;
 };
 
 const PLAYBACK_RATES = [0.5, 1, 1.5, 2];
 
 function MediaVideo(props: MediaVideoProps) {
-  const { source, focused, overlayStyle } = props;
+  const { source, focused, overlayStyle, isMuted, setIsMuted } = props;
   const { width, height } = useSafeAreaFrame();
   const { top: safeAreaTop, left: safeAreaLeft } = useSafeAreaInsets();
 
   const player = useVideoPlayer(
     VideoCache.makeCachedVideoSource(source.source),
     (player) => {
       player.audioMixingMode = "mixWithOthers";
+      player.muted = isMuted;
       player.loop = true;
       player.timeUpdateEventInterval = 1 / 15;
       player.seekTolerance = {
@@ -50,6 +54,13 @@ function MediaVideo(props: MediaVideoProps) {
     },
   );
 
+  useVideoAudioControls({
+    player,
+    focused,
+    isMuted,
+    setIsMuted,
+  });
+
   const videoTimeAtSeekStart = useSharedValue(0);
   const wasPlayingAtSeekStart = useSharedValue(false);
   const isSeeking = useSharedValue(false);
@@ -142,10 +153,8 @@ function MediaVideo(props: MediaVideoProps) {
   useEffect(() => {
     if (focused) {
       player.play();
-      player.volume = 1;
     } else {
       player.pause();
-      player.volume = 0;
     }
   }, [focused]);
 
@@ -258,6 +267,35 @@ function MediaVideo(props: MediaVideoProps) {
             <Text style={{ color: "white" }}>{playbackRate ?? 1}x</Text>
           </Touchable>
         </Animated.View>
+        <Animated.View
+          style={[
+            styles.audioControlContainer,
+            {
+              top: safeAreaTop + 60,
+              left: safeAreaLeft + 10,
+            },
+            overlayStyle,
+          ]}
+          onTouchStart={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+          }}
+        >
+          <Touchable
+            activeOpacity={0.2}
+            animationDuration={{ in: 0, out: 150 }}
+            style={styles.playbackRateButton}
+            accessibilityRole="button"
+            accessibilityLabel={isMuted ? "Unmute video" : "Mute video"}
+            onPress={() => setIsMuted(!isMuted)}
+          >
+            <FontAwesome
+              name={isMuted ? "volume-off" : "volume-up"}
+              size={20}
+              color="white"
+            />
+          </Touchable>
+        </Animated.View>
       </View>
     </GestureDetector>
   );
@@ -338,6 +376,9 @@ const styles = StyleSheet.create({
     position: "absolute",
     left: 10,
   },
+  audioControlContainer: {
+    position: "absolute",
+  },
   playbackRateButton: {
     borderRadius: 100,
     alignItems: "center",

diff --git a/components/UI/MediaViewer.tsx/MediaVideo.ios.tsx b/components/UI/MediaViewer.tsx/MediaVideo.ios.tsx
@@ -17,6 +17,7 @@ import {
 import DismountWhenBackgrounded from "../../Other/DismountWhenBackgrounded";
 import VideoCache from "../../../utils/VideoCache";
 import { Post } from "../../../api/Posts";
+import useVideoAudioControls from "./useVideoAudioControls";
 
 export type VideoItem = {
   type: "video";
@@ -28,24 +29,34 @@ type MediaVideoProps = {
   focused: boolean;
   overlayOpacity: Animated.Value;
   setIsScrollLocked: (isScrollLocked: boolean) => void;
+  isMuted: boolean;
+  setIsMuted: (isMuted: boolean) => void;
 };
 
 const PLAYBACK_RATES = [0.5, 1, 1.5, 2];
 
 function MediaVideo(props: MediaVideoProps) {
-  const { source, focused, overlayOpacity } = props;
+  const { source, focused, overlayOpacity, isMuted, setIsMuted } = props;
   const { width, height } = useSafeAreaFrame();
   const { top: safeAreaTop, left: safeAreaLeft } = useSafeAreaInsets();
 
   const player = useVideoPlayer(
     VideoCache.makeCachedVideoSource(source.source),
     (player) => {
       player.audioMixingMode = "mixWithOthers";
+      player.muted = isMuted;
       player.loop = true;
       player.timeUpdateEventInterval = 1 / 15;
     },
   );
 
+  useVideoAudioControls({
+    player,
+    focused,
+    isMuted,
+    setIsMuted,
+  });
+
   const touchStart = useRef({
     x: 0,
     y: 0,
@@ -118,10 +129,8 @@ function MediaVideo(props: MediaVideoProps) {
   useEffect(() => {
     if (focused) {
       player.play();
-      player.volume = 1;
     } else {
       player.pause();
-      player.volume = 0;
     }
   }, [focused]);
 
@@ -273,6 +282,35 @@ function MediaVideo(props: MediaVideoProps) {
           <Text style={{ color: "white" }}>{playbackRate ?? 1}x</Text>
         </Touchable>
       </Animated.View>
+      <Animated.View
+        style={[
+          styles.audioControlContainer,
+          {
+            top: safeAreaTop + 60,
+            left: safeAreaLeft + 10,
+            opacity: overlayOpacity,
+          },
+        ]}
+        onTouchStart={(e) => {
+          e.preventDefault();
+          e.stopPropagation();
+        }}
+      >
+        <Touchable
+          activeOpacity={0.2}
+          animationDuration={{ in: 0, out: 150 }}
+          style={styles.playbackRateButton}
+          accessibilityRole="button"
+          accessibilityLabel={isMuted ? "Unmute video" : "Mute video"}
+          onPress={() => setIsMuted(!isMuted)}
+        >
+          <FontAwesome
+            name={isMuted ? "volume-off" : "volume-up"}
+            size={20}
+            color="white"
+          />
+        </Touchable>
+      </Animated.View>
     </View>
   );
 }
@@ -348,6 +386,9 @@ const styles = StyleSheet.create({
     position: "absolute",
     left: 10,
   },
+  audioControlContainer: {
+    position: "absolute",
+  },
   playbackRateButton: {
     borderRadius: 100,
     alignItems: "center",

diff --git a/components/UI/MediaViewer.tsx/MediaViewer.android.tsx b/components/UI/MediaViewer.tsx/MediaViewer.android.tsx
@@ -69,6 +69,8 @@ export default function MediaViewer({
   startingColumnIndex,
   onFocusedItemChange,
   getCurrentPost,
+  isMuted,
+  setIsMuted,
   onClose,
 }: MediaViewerProps) {
   const { width, height } = useSafeAreaFrame();
@@ -475,6 +477,8 @@ export default function MediaViewer({
                   columns={columns}
                   pagerEnabled={pagerEnabled}
                   overlayStyle={overlayStyle}
+                  isMuted={isMuted}
+                  setIsMuted={setIsMuted}
                 />
               ))}
             </Animated.View>
@@ -497,6 +501,8 @@ type RowStripProps = {
   columns: SharedValue<Record<number, number>>;
   pagerEnabled: SharedValue<boolean>;
   overlayStyle: AnimatedStyleHandle<{ opacity: number }>;
+  isMuted: boolean;
+  setIsMuted: (isMuted: boolean) => void;
 };
 
 function RowStrip({
@@ -511,6 +517,8 @@ function RowStrip({
   columns,
   pagerEnabled,
   overlayStyle,
+  isMuted,
+  setIsMuted,
 }: RowStripProps) {
   const horizontalStyle = useAnimatedStyle(() => ({
     transform: [
@@ -555,6 +563,8 @@ function RowStrip({
                 source={item.source}
                 focused={centerColumn === column && isRowFocused}
                 overlayStyle={overlayStyle}
+                isMuted={isMuted}
+                setIsMuted={setIsMuted}
               />
             )}
           </View>

diff --git a/components/UI/MediaViewer.tsx/MediaViewer.ios.tsx b/components/UI/MediaViewer.tsx/MediaViewer.ios.tsx
@@ -26,6 +26,8 @@ type MediaViewerProps = {
   startingColumnIndex: number;
   onFocusedItemChange?: (index: number) => void;
   getCurrentPost?: (rowIndex: number) => Post | PostDetail | null;
+  isMuted: boolean;
+  setIsMuted: (isMuted: boolean) => void;
   onClose: () => void;
 };
 
@@ -35,6 +37,8 @@ export default function MediaViewer({
   startingColumnIndex,
   onFocusedItemChange,
   getCurrentPost,
+  isMuted,
+  setIsMuted,
   onClose,
 }: MediaViewerProps) {
   const { width, height } = useSafeAreaFrame();
@@ -301,6 +305,8 @@ export default function MediaViewer({
                       }
                       overlayOpacity={overlayOpacity.current}
                       setIsScrollLocked={setIsScrollLocked}
+                      isMuted={isMuted}
+                      setIsMuted={setIsMuted}
                     />
                   ) : null}
                 </View>

diff --git a/components/UI/MediaViewer.tsx/types.ts b/components/UI/MediaViewer.tsx/types.ts
@@ -24,5 +24,7 @@ export type MediaViewerProps = {
   startingColumnIndex: number;
   onFocusedItemChange?: (index: number) => void;
   getCurrentPost?: (rowIndex: number) => Post | PostDetail | null;
+  isMuted: boolean;
+  setIsMuted: (isMuted: boolean) => void;
   onClose: () => void;
 };
diff --git a/components/UI/MediaViewer.tsx/useVideoAudioControls.ts b/components/UI/MediaViewer.tsx/useVideoAudioControls.ts
@@ -0,0 +1,51 @@
+import { VideoPlayer } from "expo-video";
+import { useEffect } from "react";
+import { VolumeManager } from "react-native-volume-manager";
+import { isMediaVolumeIncrease } from "./videoAudioControls";
+
+export default function useVideoAudioControls({
+  player,
+  focused,
+  isMuted,
+  setIsMuted,
+}: {
+  player: VideoPlayer;
+  focused: boolean;
+  isMuted: boolean;
+  setIsMuted: (isMuted: boolean) => void;
+}) {
+  useEffect(() => {
+    player.muted = isMuted;
+  }, [isMuted, player]);
+
+  useEffect(() => {
+    if (!focused || !isMuted) return;
+
+    let cancelled = false;
+    let listener: ReturnType<typeof VolumeManager.addVolumeListener> | null =
+      null;
+    let previousVolume: number | null = null;
+
+    VolumeManager.getVolume()
+      .then(({ volume }) => {
+        if (cancelled) return;
+        previousVolume = volume;
+        listener = VolumeManager.addVolumeListener((event) => {
+          if (isMediaVolumeIncrease(previousVolume, event.volume, event.type)) {
+            setIsMuted(false);
+          }
+          if (event.type === undefined || event.type === "music") {
+            previousVolume = event.volume;
+          }
+        });
+      })
+      .catch(() => {
+        // The mute button still works if the native volume API is unavailable.
+      });
+
+    return () => {
+      cancelled = true;
+      listener?.remove();
+    };
+  }, [focused, isMuted, setIsMuted]);
+}
diff --git a/components/UI/MediaViewer.tsx/videoAudioControls.test.ts b/components/UI/MediaViewer.tsx/videoAudioControls.test.ts
@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { isMediaVolumeIncrease } from "./videoAudioControls.ts";
+
+test("detects iOS and Android media volume increases", () => {
+  assert.equal(isMediaVolumeIncrease(0.25, 0.5), true);
+  assert.equal(isMediaVolumeIncrease(0.25, 0.5, "music"), true);
+});
+
+test("ignores the initial reading, decreases, and unchanged volume", () => {
+  assert.equal(isMediaVolumeIncrease(null, 0.5), false);
+  assert.equal(isMediaVolumeIncrease(0.5, 0.25), false);
+  assert.equal(isMediaVolumeIncrease(0.5, 0.5), false);
+});
+
+test("ignores unrelated Android volume streams", () => {
+  assert.equal(isMediaVolumeIncrease(0.25, 0.5, "ring"), false);
+});
diff --git a/components/UI/MediaViewer.tsx/videoAudioControls.ts b/components/UI/MediaViewer.tsx/videoAudioControls.ts
@@ -0,0 +1,11 @@
+export function isMediaVolumeIncrease(
+  previousVolume: number | null,
+  nextVolume: number,
+  volumeType?: string,
+) {
+  return (
+    previousVolume !== null &&
+    nextVolume > previousVolume &&
+    (volumeType === undefined || volumeType === "music")
+  );
+}
diff --git a/constants/documentation.ts b/constants/documentation.ts