From c83d15d0f597ae76175b8642a094ff2065735a63 Mon Sep 17 00:00:00 2001
From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com>
Date: Mon, 15 Dec 2025 04:04:22 +0900
Subject: [PATCH 1/2] update 1

---
 .../track/audio_visualizer_widget.dart        | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/lib/src/ui/widgets/track/audio_visualizer_widget.dart b/lib/src/ui/widgets/track/audio_visualizer_widget.dart
index f30ec8b..78775c6 100644
--- a/lib/src/ui/widgets/track/audio_visualizer_widget.dart
+++ b/lib/src/ui/widgets/track/audio_visualizer_widget.dart
@@ -11,6 +11,10 @@ import '../../../context/track_reference_context.dart';
 
 enum VisualizerState { thinking, listening, active }
 
+/// Configuration options for [AudioVisualizerWidget].
+///
+/// These options control the number of bars, sizing, animation cadence, and
+/// styling used to render a simple audio spectrum / agent-state indicator.
 class AudioVisualizerWidgetOptions {
   final int barCount;
   final bool centeredBands;
@@ -77,6 +81,24 @@ class AudioVisualizerWidget extends StatelessWidget {
   final AudioVisualizerWidgetOptions options;
   final Color backgroundColor;
 
+  /// Renders an animated bar visualizer for the current audio track.
+  ///
+  /// The widget consumes a [TrackReferenceContext] from the widget tree to
+  /// discover the [sdk.AudioTrack] and associated [sdk.Participant]. When the
+  /// participant is an agent, the visualizer also reacts to agent state changes:
+  ///
+  /// - `thinking`: highlights bars in sequence.
+  /// - `initializing` / `listening`: renders a subtle "listening" pulse.
+  /// - otherwise: uses live audio samples when available.
+  ///
+  /// Example:
+  /// ```dart
+  /// ParticipantTrack(
+  ///   participant: participant,
+  ///   track: publication,
+  ///   builder: (context) => const AudioVisualizerWidget(),
+  /// );
+  /// ```
   const AudioVisualizerWidget({
     Key? key,
     this.backgroundColor = Colors.transparent,

From bf233fdc22363ce489c5440b47895fb5e37012d2 Mon Sep 17 00:00:00 2001
From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com>
Date: Mon, 15 Dec 2025 16:17:23 +0900
Subject: [PATCH 2/2] docs: improve AudioVisualizerWidget docs

---
 .changes/audio-visualizer-docs                        | 1 +
 lib/src/ui/widgets/track/audio_visualizer_widget.dart | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 .changes/audio-visualizer-docs

diff --git a/.changes/audio-visualizer-docs b/.changes/audio-visualizer-docs
new file mode 100644
index 0000000..deaf04d
--- /dev/null
+++ b/.changes/audio-visualizer-docs
@@ -0,0 +1 @@
+patch type="docs" "Add AudioVisualizerWidget documentation"
diff --git a/lib/src/ui/widgets/track/audio_visualizer_widget.dart b/lib/src/ui/widgets/track/audio_visualizer_widget.dart
index 78775c6..8e9056c 100644
--- a/lib/src/ui/widgets/track/audio_visualizer_widget.dart
+++ b/lib/src/ui/widgets/track/audio_visualizer_widget.dart
@@ -84,7 +84,7 @@ class AudioVisualizerWidget extends StatelessWidget {
   /// Renders an animated bar visualizer for the current audio track.
   ///
   /// The widget consumes a [TrackReferenceContext] from the widget tree to
-  /// discover the [sdk.AudioTrack] and associated [sdk.Participant]. When the
+  /// discover the `sdk.AudioTrack` and associated `sdk.Participant`. When the
   /// participant is an agent, the visualizer also reacts to agent state changes:
   ///
   /// - `thinking`: highlights bars in sequence.