feat(ringtones): let a music app play the alarm

"Choose from a music app…" in the sound picker browses any app that shares
its library through Android's MediaBrowserService and stores the choice as a
clockula://media URI in the existing ringtone field — no schema change, no
new permission, no internet. The music app streams with its own.

At ring time the app is asked to play through its media session. Every wait
is bounded and any failure falls back to the ordinary alarm sound: the app
won't connect or start, stalls or buffers too long, or the media stream
might not be heard (headphones or a classic Bluetooth device connected, Do
Not Disturb muting media). The ramp drives the media stream and the user's
media volume is restored when the last media ring ends.

RingAudioPlayer.start no longer suspends: vibration starts up front, the
timer collector is not held up, and a generation token keeps late work from
reviving a stopped ring.
This commit is contained in:
makiolaj committed 2026-10-02 20:44:58 +02:00
1 parent 767b9ed72d
commit f37c5f2f84
28 files changed
+1653 -46

No files matched your search

@@ -0,0 +1,60 @@
package de.jeanlucmakiola.clockula.domain
import com.google.common.truth.Truth.assertThat
import org.junit.jupiter.api.Test
/**
* A media source lives in the same string column as every other sound, so its
* encoding has to survive anything a library can name — and decoding has to
* refuse, not throw, on anything else.
*/
class MediaSourcesTest {
private val app = MediaApp("org.videolan.vlc", "org.videolan.vlc.MediaBrowserService", "VLC")
@Test
fun `a chosen item survives the round trip`() {
val ref = MediaSourceRef(app, mediaId = "playlist:42", title = "Morning & Rise = 100%")
assertThat(MediaSources.decode(MediaSources.encode(ref))).isEqualTo(ref)
}
@Test
fun `resume carries no media id`() {
val ref = MediaSourceRef(app, mediaId = null, title = "")
assertThat(MediaSources.decode(MediaSources.encode(ref))).isEqualTo(ref)
}
@Test
fun `ids and titles with reserved characters, unicode and spaces survive`() {
val ref = MediaSourceRef(app, mediaId = "a b/c?d#e&f=g+h", title = "Morgenstimmung — Grieg ✿")
assertThat(MediaSources.decode(MediaSources.encode(ref))).isEqualTo(ref)
}
@Test
fun `the encoded form is recognised and other sounds are not`() {
val uri = MediaSources.encode(MediaSourceRef(app, mediaId = "x", title = "X"))
assertThat(MediaSources.isMediaSource(uri)).isTrue()
assertThat(MediaSources.isMediaSource("content://media/1")).isFalse()
assertThat(MediaSources.isMediaSource(Ringtones.SILENT_URI)).isFalse()
assertThat(MediaSources.isMediaSource(null)).isFalse()
}
@Test
fun `anything malformed decodes to null`() {
val inputs = listOf(
null,
"content://media/1",
Ringtones.SILENT_URI,
MediaSources.PREFIX,
MediaSources.PREFIX + "svc=x",
MediaSources.PREFIX + "pkg=x",
MediaSources.PREFIX + "pkg=%zz&svc=y",
)
for (input in inputs) assertThat(MediaSources.decode(input)).isNull()
}
}
@@ -2,6 +2,9 @@ package de.jeanlucmakiola.clockula.domain.ring
import com.google.common.truth.Truth.assertThat
import com.google.common.truth.Truth.assertWithMessage
import de.jeanlucmakiola.clockula.domain.MediaApp
import de.jeanlucmakiola.clockula.domain.MediaSourceRef
import de.jeanlucmakiola.clockula.domain.MediaSources
import de.jeanlucmakiola.clockula.domain.Ringtones
import org.junit.jupiter.api.Test
@@ -41,6 +44,19 @@ class AudioSourcePolicyTest {
).inOrder()
}
@Test
fun `a music app's sound is tried first, with the defaults behind it`() {
val uri = MediaSources.encode(
MediaSourceRef(MediaApp("org.example.player", "org.example.player.Library", "Player"), "id", "Song"),
)
assertThat(AudioSourcePolicy.sourcesFor(uri)).containsExactly(
RingtoneSourceKind.MEDIA_APP,
RingtoneSourceKind.DEVICE_DEFAULT,
RingtoneSourceKind.BUILT_IN_DEFAULT,
).inOrder()
}
@Test
fun `the silent sentinel offers no audio source at all`() {
val sources = AudioSourcePolicy.sourcesFor(Ringtones.SILENT_URI)
@@ -0,0 +1,104 @@
package de.jeanlucmakiola.clockula.domain.ring
import com.google.common.truth.Truth.assertThat
import de.jeanlucmakiola.clockula.domain.ring.MediaRingPolicy.Stall
import org.junit.jupiter.api.Test
import kotlin.time.Duration
/**
* The rules that keep a ring another app plays from ever being a silent one:
* bounded waits, a watchdog that cannot be held off by "buffering", and a
* route check that refuses whenever the media stream may not be heard.
*/
class MediaRingPolicyTest {
private val tick = MediaRingPolicy.WATCH_TICK
private fun run(vararg playback: MediaPlayback): Stall =
playback.fold(Stall()) { stall, state -> MediaRingPolicy.advance(stall, state, tick) }
private fun repeat(state: MediaPlayback, over: Duration): Array<MediaPlayback> =
Array((over / tick).toInt()) { state }
@Test
fun `a brief stop is a track change, a long one is a failure`() {
val brief = run(*repeat(MediaPlayback.STOPPED, MediaRingPolicy.STALL_GRACE - tick))
val long = run(*repeat(MediaPlayback.STOPPED, MediaRingPolicy.STALL_GRACE))
assertThat(MediaRingPolicy.shouldFallBack(brief)).isFalse()
assertThat(MediaRingPolicy.shouldFallBack(long)).isTrue()
}
@Test
fun `buffering forever is a failure too`() {
val brief = run(*repeat(MediaPlayback.TRANSITIONING, MediaRingPolicy.BUFFER_GRACE - tick))
val forever = run(*repeat(MediaPlayback.TRANSITIONING, MediaRingPolicy.BUFFER_GRACE))
assertThat(MediaRingPolicy.shouldFallBack(brief)).isFalse()
assertThat(MediaRingPolicy.shouldFallBack(forever)).isTrue()
}
@Test
fun `alternating buffering and stopping cannot dodge the watchdog`() {
val states = Array((MediaRingPolicy.BUFFER_GRACE / tick).toInt()) { index ->
if (index % 2 == 0) MediaPlayback.TRANSITIONING else MediaPlayback.STOPPED
}
assertThat(MediaRingPolicy.shouldFallBack(run(*states))).isTrue()
}
@Test
fun `playing resets both clocks`() {
val stall = run(
*repeat(MediaPlayback.TRANSITIONING, MediaRingPolicy.BUFFER_GRACE - tick),
MediaPlayback.PLAYING,
)
assertThat(stall).isEqualTo(Stall())
}
@Test
fun `the target is the alarm stream's share of the media stream`() {
// Alarm at 4 of 7, media max 15: ceil(4/7 * 15) = 9.
assertThat(MediaRingPolicy.mediaVolumeTarget(alarmIndex = 4, alarmMax = 7, musicMax = 15)).isEqualTo(9)
assertThat(MediaRingPolicy.mediaVolumeTarget(alarmIndex = 7, alarmMax = 7, musicMax = 15)).isEqualTo(15)
}
@Test
fun `the media stream is never left at zero`() {
assertThat(MediaRingPolicy.mediaVolumeTarget(alarmIndex = 0, alarmMax = 7, musicMax = 15)).isEqualTo(1)
assertThat(MediaRingPolicy.mediaVolumeIndex(0f, target = 9)).isEqualTo(1)
}
@Test
fun `the ramp climbs and never passes the target`() {
val levels = listOf(0f, 0.25f, 0.5f, 0.75f, 1f, 1.5f).map { MediaRingPolicy.mediaVolumeIndex(it, target = 15) }
assertThat(levels).isInOrder()
assertThat(levels.max()).isEqualTo(15)
}
@Test
fun `degenerate stream ranges do not throw`() {
assertThat(MediaRingPolicy.mediaVolumeTarget(alarmIndex = 3, alarmMax = 0, musicMax = 15)).isEqualTo(15)
assertThat(MediaRingPolicy.mediaVolumeTarget(alarmIndex = 3, alarmMax = 7, musicMax = 0)).isEqualTo(0)
assertThat(MediaRingPolicy.mediaVolumeIndex(1f, target = 0)).isEqualTo(0)
}
@Test
fun `media is used only on a speaker, and only when Do Not Disturb lets media through`() {
val speaker = listOf(AudioOutputKind.SPEAKER, AudioOutputKind.NOT_MEDIA)
assertThat(MediaRoutePolicy.mediaAudible(dndAllowsMedia = true, outputs = speaker)).isTrue()
assertThat(MediaRoutePolicy.mediaAudible(dndAllowsMedia = false, outputs = speaker)).isFalse()
}
@Test
fun `headphones or an unknown external device route the ring to the alarm sound`() {
for (kind in listOf(AudioOutputKind.PERSONAL, AudioOutputKind.UNCERTAIN)) {
val outputs = listOf(AudioOutputKind.SPEAKER, kind)
assertThat(MediaRoutePolicy.mediaAudible(dndAllowsMedia = true, outputs = outputs)).isFalse()
}
}
}
@@ -0,0 +1,28 @@
package de.jeanlucmakiola.clockula.testing
import de.jeanlucmakiola.clockula.data.ringtones.MediaLibrary
import de.jeanlucmakiola.clockula.domain.MediaApp
import de.jeanlucmakiola.clockula.domain.MediaEntry
/**
* Other apps' libraries, scripted: [libraries] maps an app to its folders by
* parent id (`null` = root). An app absent from it refuses, as the big
* streaming apps do.
*/
class FakeMediaLibrary(
var apps: List<MediaApp> = emptyList(),
var libraries: Map<MediaApp, Map<String?, List<MediaEntry>>> = emptyMap(),
) : MediaLibrary {
var releases: Int = 0
private set
override suspend fun apps(): List<MediaApp> = apps
override suspend fun children(app: MediaApp, parentId: String?): List<MediaEntry>? =
libraries[app]?.let { it[parentId].orEmpty() }
override fun release() {
releases++
}
}
@@ -0,0 +1,122 @@
package de.jeanlucmakiola.clockula.ui.common
import com.google.common.truth.Truth.assertThat
import de.jeanlucmakiola.clockula.domain.MediaApp
import de.jeanlucmakiola.clockula.domain.MediaEntry
import de.jeanlucmakiola.clockula.domain.MediaSources
import de.jeanlucmakiola.clockula.testing.FakeMediaLibrary
import de.jeanlucmakiola.clockula.testing.MainDispatcherExtension
import kotlinx.coroutines.test.runTest
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.RegisterExtension
class MediaAppPickerViewModelTest {
@JvmField
@RegisterExtension
val main = MainDispatcherExtension()
private val player = MediaApp("org.example.player", "org.example.player.Library", "Player")
private val streamer = MediaApp("com.example.stream", "com.example.stream.Browse", "Streamer")
private val playlists = MediaEntry("playlists", "Playlists", null, browsable = true, playable = false)
private val morning = MediaEntry("pl:1", "Morning", "12 songs", browsable = true, playable = true)
private val song = MediaEntry("song:7", "Sunrise", "Artist", browsable = false, playable = true)
private val junk = MediaEntry("junk", "Neither", null, browsable = false, playable = false)
private val library = FakeMediaLibrary(
apps = listOf(player, streamer),
libraries = mapOf(
player to mapOf(
null to listOf(playlists, junk),
"playlists" to listOf(morning),
"pl:1" to listOf(song),
),
),
)
private fun opened() = MediaAppPickerViewModel(library).also { it.onOpen() }
@Test
fun `opening lists the apps that share a library`() = runTest(main.dispatcher) {
val state = opened().state.value
assertThat(state.loading).isFalse()
assertThat(state.app).isNull()
assertThat(state.apps).containsExactly(player, streamer).inOrder()
}
@Test
fun `an app's root drops entries that are neither folders nor playable`() = runTest(main.dispatcher) {
val viewModel = opened()
viewModel.onAppChosen(player)
assertThat(viewModel.state.value.entries).containsExactly(playlists)
assertThat(viewModel.state.value.refused).isFalse()
}
@Test
fun `an app that will not share says so`() = runTest(main.dispatcher) {
val viewModel = opened()
viewModel.onAppChosen(streamer)
assertThat(viewModel.state.value.refused).isTrue()
assertThat(viewModel.state.value.entries).isEmpty()
}
@Test
fun `folders nest and back climbs out of them, then out of the app`() = runTest(main.dispatcher) {
val viewModel = opened()
viewModel.onAppChosen(player)
viewModel.onFolderOpened(playlists)
viewModel.onFolderOpened(morning)
assertThat(viewModel.state.value.trail).containsExactly(playlists, morning).inOrder()
assertThat(viewModel.state.value.entries).containsExactly(song)
assertThat(viewModel.onBack()).isTrue()
assertThat(viewModel.state.value.entries).containsExactly(morning)
assertThat(viewModel.onBack()).isTrue()
assertThat(viewModel.state.value.trail).isEmpty()
assertThat(viewModel.onBack()).isTrue()
assertThat(viewModel.state.value.app).isNull()
assertThat(viewModel.onBack()).isFalse()
}
@Test
fun `a chosen item encodes the app, the id and the title`() = runTest(main.dispatcher) {
val viewModel = opened()
viewModel.onAppChosen(player)
val ref = MediaSources.decode(viewModel.uriFor(song))!!
assertThat(ref.app).isEqualTo(player)
assertThat(ref.mediaId).isEqualTo("song:7")
assertThat(ref.title).isEqualTo("Sunrise")
}
@Test
fun `resume encodes no media id, and nothing is chosen before an app is`() = runTest(main.dispatcher) {
val viewModel = opened()
assertThat(viewModel.uriFor(null)).isNull()
viewModel.onAppChosen(player)
assertThat(MediaSources.decode(viewModel.uriFor(null))!!.mediaId).isNull()
}
@Test
fun `reopening while open keeps the place, reopening after close starts over`() = runTest(main.dispatcher) {
val viewModel = opened()
viewModel.onAppChosen(player)
viewModel.onOpen()
assertThat(viewModel.state.value.app).isEqualTo(player)
viewModel.onClose()
viewModel.onOpen()
assertThat(viewModel.state.value.app).isNull()
}
}