From feae7d5958c5c0edad3c56327fcc73ccc684a5ab Mon Sep 17 00:00:00 2001
From: Marek Malek <marek.malek@swmansion.com>
Date: Thu, 2 Jul 2026 16:11:02 +0200
Subject: [PATCH 1/2] fix: broken links on audio tag

---
 packages/audiodocs/docs/core/audio-context.mdx            | 2 +-
 packages/audiodocs/docs/flags/runtime-flags.mdx           | 4 ++--
 .../docs/sources/media-element-audio-source-node.mdx      | 8 ++++----
 packages/audiodocs/docs/sources/streamer-node.mdx         | 2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/audiodocs/docs/core/audio-context.mdx b/packages/audiodocs/docs/core/audio-context.mdx
index 4cbc5c379..074222ceb 100644
--- a/packages/audiodocs/docs/core/audio-context.mdx
+++ b/packages/audiodocs/docs/core/audio-context.mdx
@@ -39,7 +39,7 @@ Creates [`MediaElementAudioSourceNode`](/docs/sources/media-element-audio-source
 
 | Parameter | Type | Description |
 | :---: | :---: | :---- |
-| `mediaElement` | `HTMLMediaElement` (web) \| [`AudioTagHandle`](/docs/experimental/audio-tag#ref-handle-audiotaghandle-methods) (native) | Media element to route into the graph. On native, wait for [`onLoad`](/docs/experimental/audio-tag#props-audioprops) on `<Audio>` before calling. |
+| `mediaElement` | `HTMLMediaElement` (web) \| [`AudioTagHandle`](/docs/sources/audio-tag#ref-handle-audiotaghandle-methods) (native) | Media element to route into the graph. On native, wait for [`onLoad`](/docs/sources/audio-tag#props-audioprops) on `<Audio>` before calling. |
 
 #### Returns [`MediaElementAudioSourceNode`](/docs/sources/media-element-audio-source-node).
 
diff --git a/packages/audiodocs/docs/flags/runtime-flags.mdx b/packages/audiodocs/docs/flags/runtime-flags.mdx
index 587f75fb5..04f3a1f11 100644
--- a/packages/audiodocs/docs/flags/runtime-flags.mdx
+++ b/packages/audiodocs/docs/flags/runtime-flags.mdx
@@ -35,9 +35,9 @@ if (!isFfmpegEnabled()) {
 | Area | API | Requires FFmpeg for |
 | :--- | :--- | :--- |
 | Streaming | [`Audio tag`](/docs/sources/audio-tag) | HLS playback |
-| Playback | [`createFileSource`](/docs/core/base-audio-context#createfilesource), [`<Audio>`](/docs/experimental/audio-tag) | Remote URL streaming, HLS (`.m3u8`), local `.mp4` / `.m4a` / `.aac`. Without FFmpeg, remote sources are downloaded and decoded with miniaudio where supported. |
+| Playback | [`createFileSource`](/docs/core/base-audio-context#createfilesource), [`<Audio>`](/docs/sources/audio-tag) | Remote URL streaming, HLS (`.m3u8`), local `.mp4` / `.m4a` / `.aac`. Without FFmpeg, remote sources are downloaded and decoded with miniaudio where supported. |
 | Decoding | [`decodeAudioData`](/docs/utils/decoding#decodeaudiodata) | `.aac`, `.mp4`, `.m4a` (and remote URLs for any format) |
-| Metadata | [`getAudioDuration`](/docs/utils/decoding#getaudioduration), [`<Audio>`](/docs/experimental/audio-tag) `preload="metadata"` | Remote `http(s):` URL duration probing |
+| Metadata | [`getAudioDuration`](/docs/utils/decoding#getaudioduration), [`<Audio>`](/docs/sources/audio-tag) `preload="metadata"` | Remote `http(s):` URL duration probing |
 | Recording | [`AudioRecorder`](/docs/inputs/audio-recorder) file output | **Android only:** `M4A`, `FLAC`, and `CAF` (WAV uses miniaudio). iOS uses system AVFoundation instead. |
 | File utils | [`concatAudioFiles`](/docs/utils/file-concatenation#concataudiofiles) | M4A concatenation (WAV uses miniaudio) |
 
diff --git a/packages/audiodocs/docs/sources/media-element-audio-source-node.mdx b/packages/audiodocs/docs/sources/media-element-audio-source-node.mdx
index 42ce89692..415ca54f9 100644
--- a/packages/audiodocs/docs/sources/media-element-audio-source-node.mdx
+++ b/packages/audiodocs/docs/sources/media-element-audio-source-node.mdx
@@ -9,7 +9,7 @@ import { ReadOnly } from '@site/src/components/Badges';
 
 The `MediaElementAudioSourceNode` is an [`AudioNode`](/docs/core/audio-node) that routes media playback into the audio graph.
 On the web it mirrors [`AudioContext.createMediaElementSource()`](https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createMediaElementSource) and accepts an `HTMLMediaElement`.
-On the native it wraps a file-backed source created by the experimental [`<Audio>`](/docs/experimental/audio-tag) tag.
+On the native it wraps a file-backed source created by the experimental [`<Audio>`](/docs/sources/audio-tag) tag.
 
 ## Constructor
 
@@ -21,7 +21,7 @@ constructor(context: BaseAudioContext, options: MediaElementAudioSourceOptions)
 
 | Parameter | Type | Default | |
 | :---: | :---: | :----: | :---- |
-| `mediaElement` | `HTMLMediaElement` (web) \| [`AudioTagHandle`](/docs/experimental/audio-tag#ref-handle-audiotaghandle-methods) (native) | — | Media element whose audio is routed into the graph. On native, wait for [`onLoad`](/docs/experimental/audio-tag#props-audioprops) before constructing this node. |
+| `mediaElement` | `HTMLMediaElement` (web) \| [`AudioTagHandle`](/docs/sources/audio-tag#ref-handle-audiotaghandle-methods) (native) | — | Media element whose audio is routed into the graph. On native, wait for [`onLoad`](/docs/sources/audio-tag#props-audioprops) before constructing this node. |
 
 Or by using [`AudioContext`](/docs/core/audio-context) factory method:
 [`AudioContext.createMediaElementSource()`](/docs/core/audio-context#createmediaelementsource)
@@ -95,7 +95,7 @@ It inherits all properties from [`AudioNode`](/docs/core/audio-node#properties).
 
 | Name | Type | Default value | Description |
 | :----: | :----: | :-------- | :------- |
-| `mediaElement` <ReadOnly /> | `HTMLMediaElement` \| [`AudioTagHandle`](/docs/experimental/audio-tag#ref-handle-audiotaghandle-methods) | — | The media element routed into the audio graph. |
+| `mediaElement` <ReadOnly /> | `HTMLMediaElement` \| [`AudioTagHandle`](/docs/sources/audio-tag#ref-handle-audiotaghandle-methods) | — | The media element routed into the audio graph. |
 
 ## Methods
 
@@ -106,4 +106,4 @@ It inherits all methods from [`AudioNode`](/docs/core/audio-node#methods).
 #### Native routing
 
 - On native, the underlying file source is disconnected from the destination when this node is created so audio is not processed twice.
-- Use the same [`AudioTagHandle`](/docs/experimental/audio-tag#ref-handle-audiotaghandle-methods) for transport controls (`play`, `pause`, `seekToTime`, `volume`).
+- Use the same [`AudioTagHandle`](/docs/sources/audio-tag#ref-handle-audiotaghandle-methods) for transport controls (`play`, `pause`, `seekToTime`, `volume`).
diff --git a/packages/audiodocs/docs/sources/streamer-node.mdx b/packages/audiodocs/docs/sources/streamer-node.mdx
index 2493d0b96..781c4e26e 100644
--- a/packages/audiodocs/docs/sources/streamer-node.mdx
+++ b/packages/audiodocs/docs/sources/streamer-node.mdx
@@ -8,7 +8,7 @@ import { Optional, ReadOnly } from '@site/src/components/Badges';
 # StreamerNode
 
 :::danger
-Deprecated. Use the [`<Audio>`](/docs/experimental/audio-tag) element with [`MediaElementAudioSourceNode`](/docs/sources/media-element-audio-source-node) for streaming audio instead to achieve the same functionality.
+Deprecated. Use the [`<Audio>`](/docs/sources/audio-tag) element with [`MediaElementAudioSourceNode`](/docs/sources/media-element-audio-source-node) for streaming audio instead to achieve the same functionality.
 :::
 
 :::caution

From 23aada0774c4c8de429557c77f45805c8840ca6a Mon Sep 17 00:00:00 2001
From: Marek Malek <marek.malek@swmansion.com>
Date: Thu, 2 Jul 2026 16:22:00 +0200
Subject: [PATCH 2/2] fix: non-existent links

---
 packages/audiodocs/docs/flags/runtime-flags.mdx                 | 2 +-
 packages/audiodocs/docs/fundamentals/best-practices.mdx         | 2 +-
 packages/audiodocs/docs/sources/audio-tag.mdx                   | 2 +-
 .../audiodocs/docs/system/playback-notification-manager.mdx     | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/audiodocs/docs/flags/runtime-flags.mdx b/packages/audiodocs/docs/flags/runtime-flags.mdx
index 04f3a1f11..04fc6313b 100644
--- a/packages/audiodocs/docs/flags/runtime-flags.mdx
+++ b/packages/audiodocs/docs/flags/runtime-flags.mdx
@@ -35,7 +35,7 @@ if (!isFfmpegEnabled()) {
 | Area | API | Requires FFmpeg for |
 | :--- | :--- | :--- |
 | Streaming | [`Audio tag`](/docs/sources/audio-tag) | HLS playback |
-| Playback | [`createFileSource`](/docs/core/base-audio-context#createfilesource), [`<Audio>`](/docs/sources/audio-tag) | Remote URL streaming, HLS (`.m3u8`), local `.mp4` / `.m4a` / `.aac`. Without FFmpeg, remote sources are downloaded and decoded with miniaudio where supported. |
+| Playback | `createFileSource`, [`<Audio>`](/docs/sources/audio-tag) | Remote URL streaming, HLS (`.m3u8`), local `.mp4` / `.m4a` / `.aac`. Without FFmpeg, remote sources are downloaded and decoded with miniaudio where supported. |
 | Decoding | [`decodeAudioData`](/docs/utils/decoding#decodeaudiodata) | `.aac`, `.mp4`, `.m4a` (and remote URLs for any format) |
 | Metadata | [`getAudioDuration`](/docs/utils/decoding#getaudioduration), [`<Audio>`](/docs/sources/audio-tag) `preload="metadata"` | Remote `http(s):` URL duration probing |
 | Recording | [`AudioRecorder`](/docs/inputs/audio-recorder) file output | **Android only:** `M4A`, `FLAC`, and `CAF` (WAV uses miniaudio). iOS uses system AVFoundation instead. |
diff --git a/packages/audiodocs/docs/fundamentals/best-practices.mdx b/packages/audiodocs/docs/fundamentals/best-practices.mdx
index 374e1f942..965497cd1 100644
--- a/packages/audiodocs/docs/fundamentals/best-practices.mdx
+++ b/packages/audiodocs/docs/fundamentals/best-practices.mdx
@@ -18,7 +18,7 @@ user experience, and maintainability. Here are some key best practices to consid
 
 - **Suspend when not in use**: Suspend the `AudioContext` when audio is not needed to save system resources and battery life, especially on mobile devices.
   Running `AudioContext` is still playing silence even if there is no playing source node connected to the [`destination`](/docs/core/base-audio-context#properties).
-  Additionally, on iOS devices, the state of the `AudioContext` is directly related with state of the lock screen. If running `AudioContext` exists, it is impossible to set lock screen state to [`state_paused`](/docs/system/audio-manager#lockscreeninfo).
+  Additionally, on iOS devices, the state of the `AudioContext` is directly related with state of the lock screen. If running `AudioContext` exists, it is impossible to set lock screen state to `state_paused`.
 
 ## React hooks vs React Native Audio API
 
diff --git a/packages/audiodocs/docs/sources/audio-tag.mdx b/packages/audiodocs/docs/sources/audio-tag.mdx
index 1ff218b4c..70e53f7d8 100644
--- a/packages/audiodocs/docs/sources/audio-tag.mdx
+++ b/packages/audiodocs/docs/sources/audio-tag.mdx
@@ -42,7 +42,7 @@ Only **required** field is a `source`. Callbacks default to no-ops if omitted.
 | `source` | `AudioSource` | — | Asset id (`require(...)`), string URI/path, or `{ uri?, headers? }` for HTTP(S). |
 | `context` | `BaseAudioContext` | — | Optional. Native: implicit [`AudioContext`](/docs/core/audio-context) when omitted. Web: unused for HTML element playback. |
 | `autoPlay` | `boolean` | `false` | Start playback after load. |
-| `controls` | `boolean` | `false` | When `true`, renders default [`AudioControls`](#audiocontrols) above `children`. |
+| `controls` | `boolean` | `false` | When `true`, renders default `AudioControls` above `children`. |
 | `loop` | `boolean` | `false` | Loop playback. |
 | `muted` | `boolean` | `false` | Muted state. |
 | `volume` | `number` | `1` | Linear volume passed to the underlying source. |
diff --git a/packages/audiodocs/docs/system/playback-notification-manager.mdx b/packages/audiodocs/docs/system/playback-notification-manager.mdx
index 58947dd8d..9e4ee3204 100644
--- a/packages/audiodocs/docs/system/playback-notification-manager.mdx
+++ b/packages/audiodocs/docs/system/playback-notification-manager.mdx
@@ -126,7 +126,7 @@ Add an event listener for notification actions.
 |  Parameter  | Type | Description |
 | :---------: | :------: | :------- |
 | `eventName` | [`PlaybackNotificationEventName`](playback-notification-manager#playbacknotificationeventname) | The event to listen for |
-| `callback`  | [`SystemEventCallback`](/docs/system/audio-manager#systemeventname--remotecommandeventname) | Callback function |
+| `callback`  | [`SystemEventCallback`](/docs/system/audio-manager#systemeventname) | Callback function |
 
 #### Returns [`AudioEventSubscription`](/docs/system/audio-manager#audioeventsubscription).