From c10c60134c8dd6e8f84f3fc1337fa3618228d2b0 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Mon, 13 Oct 2025 16:06:08 +0200
Subject: [PATCH] Add some comment

---
 .../libraries/textcomposer/model/VoiceMessageState.kt    | 2 ++
 .../libraries/voicerecorder/api/VoiceRecorderState.kt    | 9 ++++++---
 .../libraries/voicerecorder/impl/DefaultVoiceRecorder.kt | 2 ++
 .../voicerecorder/impl/audio/AudioLevelCalculator.kt     | 3 +++
 4 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/libraries/textcomposer/impl/src/main/kotlin/io/element/android/libraries/textcomposer/model/VoiceMessageState.kt b/libraries/textcomposer/impl/src/main/kotlin/io/element/android/libraries/textcomposer/model/VoiceMessageState.kt
index 8fa0ffbe55..46622ec59f 100644
--- a/libraries/textcomposer/impl/src/main/kotlin/io/element/android/libraries/textcomposer/model/VoiceMessageState.kt
+++ b/libraries/textcomposer/impl/src/main/kotlin/io/element/android/libraries/textcomposer/model/VoiceMessageState.kt
@@ -21,11 +21,13 @@ sealed interface VoiceMessageState {
         val showCursor: Boolean,
         val playbackProgress: Float,
         val time: Duration,
+        // Values are between 0 and 1
         val waveform: ImmutableList<Float>,
     ) : VoiceMessageState
 
     data class Recording(
         val duration: Duration,
+        // Values are between 0 and 1
         val levels: ImmutableList<Float>,
     ) : VoiceMessageState
 }
diff --git a/libraries/voicerecorder/api/src/main/kotlin/io/element/android/libraries/voicerecorder/api/VoiceRecorderState.kt b/libraries/voicerecorder/api/src/main/kotlin/io/element/android/libraries/voicerecorder/api/VoiceRecorderState.kt
index cc4dc0238c..2765e8e832 100644
--- a/libraries/voicerecorder/api/src/main/kotlin/io/element/android/libraries/voicerecorder/api/VoiceRecorderState.kt
+++ b/libraries/voicerecorder/api/src/main/kotlin/io/element/android/libraries/voicerecorder/api/VoiceRecorderState.kt
@@ -22,16 +22,19 @@ sealed interface VoiceRecorderState {
      * The recorder is currently recording.
      *
      * @property elapsedTime The elapsed time since the recording started.
-     * @property levels The current audio levels of the recording as a fraction of 1.
+     * @property levels The current audio levels of the recording as a fraction of 1. All values are between 0 and 1.
      */
-    data class Recording(val elapsedTime: Duration, val levels: List<Float>) : VoiceRecorderState
+    data class Recording(
+        val elapsedTime: Duration,
+        val levels: List<Float>,
+    ) : VoiceRecorderState
 
     /**
      * The recorder has finished recording.
      *
      * @property file The recorded file.
      * @property mimeType The mime type of the file.
-     * @property waveform The waveform of the recording.
+     * @property waveform The waveform of the recording. All values are between 0 and 1.
      * @property duration The total time spent recording.
      */
     data class Finished(
diff --git a/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/DefaultVoiceRecorder.kt b/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/DefaultVoiceRecorder.kt
index 624282edef..b4d48e1d14 100644
--- a/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/DefaultVoiceRecorder.kt
+++ b/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/DefaultVoiceRecorder.kt
@@ -63,6 +63,8 @@ class DefaultVoiceRecorder(
     private var outputFile: File? = null
     private var audioReader: AudioReader? = null
     private var recordingJob: Job? = null
+
+    // List of Float between 0 and 1 representing the audio levels
     private val levels: MutableList<Float> = mutableListOf()
     private val lock = Mutex()
 
diff --git a/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/audio/AudioLevelCalculator.kt b/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/audio/AudioLevelCalculator.kt
index d58ca3e4e2..64c0fc9ddb 100644
--- a/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/audio/AudioLevelCalculator.kt
+++ b/libraries/voicerecorder/impl/src/main/kotlin/io/element/android/libraries/voicerecorder/impl/audio/AudioLevelCalculator.kt
@@ -7,6 +7,8 @@
 
 package io.element.android.libraries.voicerecorder.impl.audio
 
+import androidx.annotation.FloatRange
+
 interface AudioLevelCalculator {
     /**
      * Calculate the audio level of the audio buffer.
@@ -14,5 +16,6 @@ interface AudioLevelCalculator {
      * @param buffer The audio buffer containing 16bit PCM audio data.
      * @return A float value between 0 and 1 proportional to the audio level.
      */
+    @FloatRange(from = 0.0, to = 1.0)
     fun calculateAudioLevel(buffer: ShortArray): Float
 }