Skip to content

Native Android client for Spotify, built with Jetpack Compose

AutoMix: measurement bench for segue plans

kota-zoc1f1bf5dc5bf
diff --git a/base/automix/src/main/kotlin/app/myspoti/automix/segue/SeguePolicy.kt b/base/automix/src/main/kotlin/app/myspoti/automix/segue/SeguePolicy.kt
index 9d01e913..e109bf58 100644
--- a/base/automix/src/main/kotlin/app/myspoti/automix/segue/SeguePolicy.kt
+++ b/base/automix/src/main/kotlin/app/myspoti/automix/segue/SeguePolicy.kt
@@ -185,11 +185,15 @@ object SeguePolicy {
return generateSequence(MixPlanner.firstDown(g, down, from)) { it + bar }.takeWhile { it <= to }
}
+ /** B's first downbeat at its attack, never before the song's start. */
+ private fun firstEntry(g: Grid?): Double =
+ if (g != null) MixPlanner.firstDown(g, b.headDown, max(0.0, b.contentStart - 0.08)).coerceAtLeast(0.0) else b.contentStart
+
/** B's useful attack, its first boundaries; leaving out a start must be worth its note. */
private fun entries(g: Grid?, spanUs: Long, phrases: Boolean): List<Point> {
val limit = us(b.contentEnd)
val startUs = us(b.contentStart)
- val first: Double = if (g != null) MixPlanner.firstDown(g, b.headDown, b.contentStart - 0.08) else b.contentStart
+ val first = firstEntry(g)
val out = ArrayList<Point>()
out += Point(us(first), b.barAt(first + 0.05), 1.0, true)
if (g != null) {
@@ -245,6 +249,8 @@ object SeguePolicy {
val score = score(e, n, lengthUs, spanUs, phaseMedian, deviation, lanes)
if (best == null || score.total > best.score) best = Found(plan, score.total, swap)
}
+ // The longest length that works: shorter only when it has to be.
+ if (best != null && best.score >= t.thresholdLocked) break
}
return settle(level, tally, best, t.thresholdLocked)
}
@@ -269,6 +275,7 @@ object SeguePolicy {
val score = score(e, n, lengthUs, lengthUs, null, 0, lanes)
if (best == null || score.total > best.score) best = Found(plan, score.total, t.filteredSwapShare)
}
+ if (best != null && best.score >= t.thresholdFiltered) break
}
return settle(level, tally, best, t.thresholdFiltered)
}
@@ -301,7 +308,7 @@ object SeguePolicy {
val targetUs = max(r.earliestExitUs, endUs - lengthUs)
val bar = a.barStarts.lastOrNull { us(it) in r.earliestExitUs..targetUs && targetUs - us(it) <= t.simpleFadeUs }
val exitUs = bar?.let(::us) ?: targetUs
- val entryTime = gb?.let { MixPlanner.firstDown(it, b.headDown, b.contentStart - 0.08) } ?: b.contentStart
+ val entryTime = firstEntry(gb)
val e = Point(exitUs, a.barAt(exitUs / 1e6 + 0.05), 1.0, true)
val n = Point(us(entryTime), b.barAt(entryTime + 0.05), 1.0, true)
val tally = Tally().also { it.seen = 1 }
diff --git a/base/automix/src/main/kotlin/app/myspoti/automix/segue/SegueTuning.kt b/base/automix/src/main/kotlin/app/myspoti/automix/segue/SegueTuning.kt
index 332f2ff5..61b867db 100644
--- a/base/automix/src/main/kotlin/app/myspoti/automix/segue/SegueTuning.kt
+++ b/base/automix/src/main/kotlin/app/myspoti/automix/segue/SegueTuning.kt
@@ -158,5 +158,10 @@ data class SegueTuning(
/** The band where two bass lines mask each other [U]. Fixed at analysis: not varied by the harness. */
const val BASS_LOW_HZ = 20.0
const val BASS_HIGH_HZ = 150.0
+
+ /** Measurement: how far each parameter is varied [I], and the corpus split for tuning, validation, final test [I]. */
+ const val STABILITY_RANGE = 0.20
+ const val SPLIT_TUNING_SHARE = 0.60
+ const val SPLIT_VALIDATION_SHARE = 0.20
}
}
diff --git a/base/automix/src/test/kotlin/app/myspoti/automix/Bench.kt b/base/automix/src/test/kotlin/app/myspoti/automix/Bench.kt
index 1b28e179..07078b53 100644
--- a/base/automix/src/test/kotlin/app/myspoti/automix/Bench.kt
+++ b/base/automix/src/test/kotlin/app/myspoti/automix/Bench.kt
@@ -12,7 +12,7 @@ import kotlin.math.abs
* reference. Commands: `analyze <dir>` prints tempo, beat and downbeat agreement with the reference.
*/
fun main(args: Array<String>) {
- val cmd = args.getOrNull(0) ?: return println("usage: analyze <dir> | plan <dir> a,b [render] | matrix <dir> [long] [whole] [fresh]")
+ val cmd = args.getOrNull(0) ?: return println("usage: analyze <dir> | plan <dir> a,b [render] | matrix <dir> [long] [whole] [fresh] | segue <dir> split|matrix|measure|render|stability ...")
val dir = args.getOrNull(1)?.let(::File) ?: return println("missing corpus directory")
when (cmd) {
"analyze" -> {
@@ -44,6 +44,7 @@ fun main(args: Array<String>) {
println(String.format(java.util.Locale.ROOT, "%s\t%.0f BPM\tq25 %.2f q50 %.2f q75 %.2f\t%s", n, a.bpm, q(0.25), q(0.5), q(0.75),
a.barVocalRisk.joinToString("") { (it * 9.99f).toInt().coerceIn(0, 9).toString() }))
}
+ "segue" -> app.myspoti.automix.segue.SegueBench.run(dir, args.drop(2))
"tempo" -> dir.listFiles { f -> f.name.endsWith(".f32") }!!.map { it.nameWithoutExtension }.sorted().forEach { tempoDebug(dir, it) }
else -> println("unknown $cmd")
}
diff --git a/base/automix/src/test/kotlin/app/myspoti/automix/segue/SegueBench.kt b/base/automix/src/test/kotlin/app/myspoti/automix/segue/SegueBench.kt
new file mode 100644
index 00000000..78bc1c5b
--- /dev/null
+++ b/base/automix/src/test/kotlin/app/myspoti/automix/segue/SegueBench.kt
@@ -0,0 +1,383 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+package app.myspoti.automix.segue
+
+import app.myspoti.automix.BenchCache
+import app.myspoti.automix.BeatTracker
+import app.myspoti.automix.Features
+import app.myspoti.automix.Render
+import app.myspoti.automix.TrackAnalysis
+import java.io.File
+import java.io.RandomAccessFile
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.security.MessageDigest
+import java.util.Locale
+import kotlin.math.abs
+import kotlin.math.log10
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.sqrt
+
+/**
+ * Measures segue plans on a corpus that stays out of the repository. `<dir>` holds `sNN.f32` (stereo
+ * float 44.1 kHz) and optionally `names.txt` (`id|title - artist.ext`, for the split). Every command
+ * prints tab-separated rows and a summary, and takes `fold=tuning|validation|test`.
+ */
+object SegueBench {
+ private val L = Locale.ROOT
+ private const val RATE = Render.SR
+
+ fun run(dir: File, args: List<String>) {
+ val fold = args.firstOrNull { it.startsWith("fold=") }?.removePrefix("fold=")
+ val limit = args.firstOrNull { it.startsWith("limit=") }?.removePrefix("limit=")?.toInt()
+ val rest = args.filter { !it.contains('=') }
+ tuning = args.firstOrNull { it.startsWith("with=") }?.removePrefix("with=")?.split(',')?.fold(SegueTuning()) { t, kv ->
+ val (k, v) = kv.split(':'); SegueCorpus.withValue(t, k, v.toDouble())
+ } ?: SegueTuning()
+ when (rest.firstOrNull()) {
+ "split" -> printSplit(dir)
+ "matrix" -> matrix(dir, fold, rest.contains("fresh"))
+ "measure" -> measure(dir, fold, limit ?: 100, args.firstOrNull { it.startsWith("only=") }?.removePrefix("only="))
+ "stability" -> stability(dir, fold, limit ?: 60)
+ "render" -> render(dir, rest.drop(1).filter { it.contains(',') })
+ else -> println("segue <dir> split | matrix [fresh] | measure [limit=N] | stability [limit=N] | render a,b ... ; all take fold=")
+ }
+ }
+
+ // ── The corpus and its split ──
+
+ private fun names(dir: File, fold: String?): List<String> {
+ val all = dir.listFiles { f -> f.name.endsWith(".f32") && !f.name.contains(".tmp.") && !f.name.startsWith("mix-") }.orEmpty().map { it.nameWithoutExtension }.sorted()
+ if (fold == null) return all
+ val split = SegueCorpus.split(SegueCorpus.read(File(dir, "names.txt")))
+ return all.filter { split[it] == fold }
+ }
+
+ private fun analyses(dir: File, names: List<String>, fresh: Boolean = false) = names.associateWith { BenchCache.analysis(dir, it, fresh).analysis }
+
+ private fun printSplit(dir: File) {
+ val rows = SegueCorpus.read(File(dir, "names.txt"))
+ val split = SegueCorpus.split(rows)
+ for (r in rows) println("${r.id}\t${split[r.id]}")
+ println("summary\t" + split.values.groupingBy { it }.eachCount().toSortedMap().entries.joinToString("\t") { "${it.key}=${it.value}" } +
+ "\tartists=${rows.map { it.artist }.toSet().size}")
+ }
+
+ /** Ordered pairs, spread evenly when there is a limit: the same pairs on every run. */
+ private fun pairs(names: List<String>, limit: Int?): List<Pair<String, String>> {
+ val all = names.flatMap { a -> names.filter { it != a }.map { a to it } }
+ if (limit == null || limit >= all.size) return all
+ return all.sortedBy { (a, b) -> SegueCodec.hex("$a|$b".toByteArray()) }.take(limit)
+ }
+
+ /** `with=field:value,field:value`: a what-if on the bench only; the plans' parameters stay in [SegueTuning]. */
+ private var tuning = SegueTuning()
+
+ private fun request(a: TrackAnalysis, b: TrackAnalysis, t: SegueTuning = tuning) = SegueRequest(a, b, tuning = t)
+
+ // ── Every pair: which level, why ──
+
+ private fun matrix(dir: File, fold: String?, fresh: Boolean) {
+ val names = names(dir, fold)
+ val songs = analyses(dir, names, fresh)
+ println(String.format(L, "songs\t%d\twith phase on tail %d\ton head %d\treliable tail %d", names.size,
+ songs.values.count { it.tailPhase != null }, songs.values.count { it.headPhase != null }, songs.values.count { it.tail?.let { g -> g.steadiness >= 0.6 && g.driftMs <= 30 } == true }))
+ val levels = java.util.EnumMap<SegueLevel, Int>(SegueLevel::class.java)
+ val causes = HashMap<String, Int>(); val refused = HashMap<String, Int>()
+ val ms = ArrayList<Double>(); var unstable = 0; var invalid = 0
+ val lengths = ArrayList<Double>(); val cuts = ArrayList<Double>()
+ println("pair\tlevel\tseconds\texit\tentry\trate\tscore\tms\twhy")
+ for ((x, y) in pairs(names, null)) {
+ val a = songs.getValue(x); val b = songs.getValue(y)
+ val t0 = System.nanoTime()
+ val d = SeguePolicy.decide(request(a, b))
+ ms += (System.nanoTime() - t0) / 1e6
+ levels[d.level] = (levels[d.level] ?: 0) + 1
+ for (at in d.attempts) {
+ causes.merge("${at.level}:${at.cause}", 1, Int::plus)
+ if (at.cause == SegueCause.GUARDS) Regex("([A-Z_0-9]+)×").findAll(at.detail).forEach { refused.merge("${at.level.cls}:${it.groupValues[1]}", 1, Int::plus) }
+ }
+ if (SeguePolicy.decide(request(a, b)).fingerprint != d.fingerprint) unstable++
+ d.plan?.let { p ->
+ if (SegueValidator.against(p, SeguePolicy.facts(a, b).first, SeguePolicy.facts(a, b).second).isNotEmpty()) invalid++
+ lengths += p.span.lengthUs / 1e6
+ cuts += max(0.0, app.myspoti.automix.MixPlanner.musicEnd(a) - (p.outgoing.anchorUs + p.span.lengthUs) / 1e6)
+ }
+ val p = d.plan
+ println(String.format(L, "%s,%s\t%s\t%.3f\t%.3f\t%.3f\t%d\t%s\t%.2f\t%s", x, y, d.level, (p?.span?.lengthUs ?: 0) / 1e6, (p?.outgoing?.anchorUs ?: 0) / 1e6,
+ (p?.incoming?.anchorUs ?: 0) / 1e6, p?.incoming?.ratePpm ?: 0, d.score?.let { String.format(L, "%.3f", it) } ?: "-", ms.last(), d.why))
+ }
+ ms.sort(); lengths.sort(); cuts.sort()
+ println("summary\tpairs=${ms.size}\t" + levels.entries.joinToString("\t") { "${it.key}=${it.value}" } + "\tnot_reproducible=$unstable\tinvalid=$invalid")
+ println(String.format(L, "summary\tplan_median_ms=%.2f\tplan_p95_ms=%.2f\tmedian_seconds=%.1f\tmedian_cut_seconds=%.1f", at(ms, 0.5), at(ms, 0.95), at(lengths, 0.5), at(cuts, 0.5)))
+ for ((k, v) in causes.toSortedMap()) println("cause\t$k\t$v")
+ for ((k, v) in refused.toSortedMap()) println("refused\t$k\t$v")
+ }
+
+ private fun at(x: List<Double>, q: Double) = if (x.isEmpty()) Double.NaN else x[((x.size - 1) * q).toInt()]
+
+ // ── Rendering: both stems through the same sound as the phone ──
+
+ private class Stems(val a: FloatArray, val b: FloatArray, val dryA: FloatArray, val dryB: FloatArray, val preFrames: Int)
+
+ private fun stems(dir: File, x: String, y: String, p: SeguePlan, pre: Double, post: Double, cache: MutableMap<String, FloatArray>, tmp: File): Stems {
+ val length = p.span.lengthUs / 1e6
+ val frames = ((pre + length + post) * RATE).toInt()
+ val pcmA = cache.getOrPut(x) { Render.stereo(File(dir, "$x.f32")) }
+ val pcmB = cache.getOrPut(y) { Render.stereo(File(dir, "$y.f32")) }
+ val dryA = slice(pcmA, ((p.outgoing.anchorUs / 1e6 - pre) * RATE).toInt(), frames)
+ val a = dryA.copyOf()
+ SegueDeck(p, LaneSide.OUTGOING, RATE, 2).process(a, frames, p.outgoing.anchorUs - (pre * 1e6).toLong())
+ val rate = p.incoming.ratePpm.toDouble() / SegueFormat.RATE_NOMINAL
+ val startUs = p.incoming.anchorUs - (pre * rate * 1e6).toLong()
+ val sourceFrames = (frames * rate).toInt() + RATE
+ val dryB = slice(pcmB, Math.floorDiv(startUs * RATE, 1_000_000L).toInt(), sourceFrames)
+ val b = dryB.copyOf()
+ SegueDeck(p, LaneSide.INCOMING, RATE, 2).process(b, sourceFrames, startUs)
+ return Stems(a, fit(stretch(b, rate, tmp), frames), dryA, fit(stretch(dryB, rate, tmp), frames), (pre * RATE).toInt())
+ }
+
+ private fun slice(pcm: FloatArray, firstFrame: Int, frames: Int): FloatArray {
+ val out = FloatArray(frames * 2)
+ for (i in 0 until frames) {
+ val f = firstFrame + i
+ if (f < 0 || 2 * f + 1 >= pcm.size) continue
+ out[2 * i] = pcm[2 * f]; out[2 * i + 1] = pcm[2 * f + 1]
+ }
+ return out
+ }
+
+ private fun fit(x: FloatArray, frames: Int) = if (x.size == frames * 2) x else x.copyOf(frames * 2)
+
+ /** The time stretch the phone's AudioTrack does, pitch kept: atempo's the nearest on a desktop. */
+ private fun stretch(x: FloatArray, rate: Double, tmp: File): FloatArray {
+ if (abs(rate - 1) < 1e-9) return x
+ val input = File(tmp, "segue.in.f32"); val output = File(tmp, "segue.out.f32")
+ val bytes = ByteBuffer.allocate(x.size * 4).order(ByteOrder.LITTLE_ENDIAN)
+ bytes.asFloatBuffer().put(x)
+ RandomAccessFile(input, "rw").use { it.setLength(0); it.write(bytes.array()) }
+ val cmd = listOf("ffmpeg", "-v", "error", "-y", "-f", "f32le", "-ar", "$RATE", "-ac", "2", "-i", input.path,
+ "-af", String.format(L, "atempo=%.6f", rate), "-f", "f32le", "-ar", "$RATE", "-ac", "2", output.path)
+ check(ProcessBuilder(cmd).inheritIO().start().waitFor() == 0) { "ffmpeg failed" }
+ return Render.stereo(output)
+ }
+
+ private fun mix(s: Stems) = FloatArray(s.a.size) { s.a[it] + s.b[it] }
+
+ private fun envelope(stereo: FloatArray, fromFrame: Int, toFrame: Int): FloatArray {
+ val n = (toFrame - fromFrame) / 2
+ val mid = FloatArray(n) { i -> val f = 2 * (fromFrame + 2 * i); (stereo[f] + stereo[f + 1] + stereo[f + 2] + stereo[f + 3]) / 4 }
+ return BeatTracker.envelope(Features.of(mid, null))
+ }
+
+ // ── Measuring ──
+
+ /** [limit] pairs that got a plan, from those whose level starts with [only]. */
+ private fun measure(dir: File, fold: String?, limit: Int, only: String?) {
+ val names = names(dir, fold)
+ val songs = analyses(dir, names)
+ val tmp = File(dir, ".segue-tmp").apply { mkdirs() }
+ val cache = object : LinkedHashMap<String, FloatArray>(16, .75f, true) { override fun removeEldestEntry(e: MutableMap.MutableEntry<String, FloatArray>?) = size > 16 }
+ val results = ArrayList<Pair<SegueLevel, SegueMetrics.Result>>()
+ println("pair\tlevel\tseconds\tpeak\tclipped\tjump_db\tclick\tgap_ms\tresidual_ms\tmeasured_ms")
+ for ((x, y) in pairs(names, Int.MAX_VALUE).sortedBy { (a, b) -> SegueCodec.hex("$a|$b".toByteArray()) }) {
+ if (results.size >= limit) break
+ val d = SeguePolicy.decide(request(songs.getValue(x), songs.getValue(y)))
+ val p = d.plan ?: continue
+ if (only != null && !d.level.name.startsWith(only)) continue
+ val pre = 4.0
+ val s = stems(dir, x, y, p, pre, 4.0, cache, tmp)
+ val win = (p.span.lengthUs / 1e6 * RATE).toInt()
+ val locked = p.pulse.state == PulseState.LOCKED
+ val lag = if (locked) SegueMetrics.lagMs(envelope(s.dryA, s.preFrames, s.preFrames + win), envelope(s.dryB, s.preFrames, s.preFrames + win), Features.FPS) else null
+ val r = SegueMetrics.of(mix(s), s.preFrames, win, RATE, p.pulse.residualUs?.let { it / 1000.0 }, lag)
+ results += d.level to r
+ println(String.format(L, "%s,%s\t%s\t%.3f\t%.3f\t%d\t%.2f\t%.1f\t%.1f\t%s\t%s", x, y, d.level, win.toDouble() / RATE, r.peak, r.clipped, r.jumpDb, r.click, r.gapMs,
+ r.residualMs?.let { String.format(L, "%.1f", it) } ?: "-", r.measuredMs?.let { String.format(L, "%.1f", it) } ?: "-"))
+ }
+ tmp.deleteRecursively()
+ fun line(label: String, rs: List<SegueMetrics.Result>) {
+ if (rs.isEmpty()) return
+ fun q(f: (SegueMetrics.Result) -> Double?, v: Double) = at(rs.mapNotNull(f).sorted(), v)
+ println(String.format(L, "summary\t%s\tn=%d\tpeak_p95=%.2f\twith_clipping=%d\tjump_median=%.2f\tjump_p95=%.2f\tclick_p95=%.2f\tgap_p95_ms=%.1f\tresidual_median_ms=%.1f\tmeasured_median_ms=%.1f\tmeasured_p95_ms=%.1f",
+ label, rs.size, q({ it.peak }, 0.95), rs.count { it.clipped > 0 }, q({ it.jumpDb }, 0.5), q({ it.jumpDb }, 0.95), q({ it.click }, 0.95), q({ it.gapMs }, 0.95),
+ q({ it.residualMs }, 0.5), q({ it.measuredMs?.let(::abs) }, 0.5), q({ it.measuredMs?.let(::abs) }, 0.95)))
+ }
+ line("all", results.map { it.second })
+ for (l in SegueLevel.values()) line(l.name, results.filter { it.first == l }.map { it.second })
+ }
+
+ private fun render(dir: File, asked: List<String>) {
+ val tmp = File(dir, ".segue-tmp").apply { mkdirs() }
+ val cache = HashMap<String, FloatArray>()
+ for (pair in asked) {
+ val (x, y) = pair.split(',')
+ val d = SeguePolicy.decide(request(BenchCache.analysis(dir, x).analysis, BenchCache.analysis(dir, y).analysis))
+ val p = d.plan
+ println("$x,$y ${d.level} ${d.fingerprint ?: ""} | ${d.why}")
+ if (p == null) continue
+ Render.writeWav(File(dir, "mix-$x-$y.wav"), mix(stems(dir, x, y, p, 12.0, 15.0, cache, tmp)))
+ }
+ tmp.deleteRecursively()
+ }
+
+ // ── Stability: each parameter ±STABILITY_RANGE ──
+
+ private fun stability(dir: File, fold: String?, limit: Int) {
+ val names = names(dir, fold)
+ val songs = analyses(dir, names)
+ val sample = pairs(names, limit)
+ val base = sample.map { (x, y) -> SeguePolicy.decide(request(songs.getValue(x), songs.getValue(y))) }
+ println("parameter\tfactor\tlevel_changed\tplan_changed\tpairs")
+ val inert = ArrayList<String>()
+ for ((name, tuned) in SegueCorpus.variations(tuning)) {
+ var levels = 0; var plans = 0
+ for (i in sample.indices) {
+ val d = SeguePolicy.decide(request(songs.getValue(sample[i].first), songs.getValue(sample[i].second), tuned))
+ if (d.level != base[i].level) levels++
+ if (d.fingerprint != base[i].fingerprint) plans++
+ }
+ println("$name\t$levels\t$plans\t${sample.size}")
+ if (plans == 0) inert += name
+ }
+ println("summary\tinert_variations=${inert.size}\t${inert.joinToString(",")}")
+ }
+}
+
+/** What is measured on a render: its integrity, then its timing against the plan's own expectation. */
+object SegueMetrics {
+ class Result(val peak: Double, val clipped: Int, val jumpDb: Double, val click: Double, val gapMs: Double, val residualMs: Double?, val measuredMs: Double?)
+
+ fun of(mix: FloatArray, preFrames: Int, windowFrames: Int, rate: Int, residualMs: Double?, measuredMs: Double?): Result {
+ var peak = 0.0; var clipped = 0
+ for (v in mix) { val m = abs(v).toDouble(); if (m > peak) peak = m; if (m > 1.0) clipped++ }
+ val w = (0.4 * rate).toInt()
+ val before = rms(mix, preFrames - w, preFrames); val after = rms(mix, preFrames + windowFrames, preFrames + windowFrames + w)
+ return Result(peak, clipped, abs(db(after) - db(before)), click(mix, preFrames, windowFrames, rate), longestGapMs(mix, preFrames, preFrames + windowFrames + w, rate), residualMs, measuredMs)
+ }
+
+ private fun db(x: Double) = 20 * log10(max(x, 1e-6))
+
+ private fun rms(stereo: FloatArray, from: Int, to: Int): Double {
+ val a = max(0, from); val b = min(stereo.size / 2, to)
+ if (b <= a) return 0.0
+ var s = 0.0
+ for (i in 2 * a until 2 * b) s += stereo[i] * stereo[i]
+ return sqrt(s / (2 * (b - a)))
+ }
+
+ /** The largest sample step at the window's edges over the song's own largest step just before them. */
+ fun click(stereo: FloatArray, preFrames: Int, windowFrames: Int, rate: Int): Double {
+ fun step(from: Int, to: Int): Double {
+ var m = 0.0
+ for (f in max(1, from) until min(stereo.size / 2, to)) for (c in 0..1) m = max(m, abs(stereo[2 * f + c] - stereo[2 * (f - 1) + c]).toDouble())
+ return m
+ }
+ val edge = (0.01 * rate).toInt()
+ val song = step(preFrames - rate, preFrames - edge)
+ val edges = max(step(preFrames - edge, preFrames + edge), step(preFrames + windowFrames - edge, preFrames + windowFrames + edge))
+ return if (song > 0) edges / song else if (edges > 0) Double.POSITIVE_INFINITY else 0.0
+ }
+
+ /** The longest stretch under −60 dBFS: a mix that falls silent is broken, however good its score. */
+ fun longestGapMs(stereo: FloatArray, from: Int, to: Int, rate: Int): Double {
+ var run = 0; var top = 0
+ for (f in max(0, from) until min(stereo.size / 2, to)) {
+ if (abs(stereo[2 * f]) < 1e-3f && abs(stereo[2 * f + 1]) < 1e-3f) { run++; top = max(top, run) } else run = 0
+ }
+ return top * 1000.0 / rate
+ }
+
+ /** The lag of [b]'s onsets on [a]'s, in ms, within ±100 ms; null without onsets to compare. */
+ fun lagMs(a: FloatArray, b: FloatArray, fps: Double): Double? {
+ val n = min(a.size, b.size)
+ val reach = (0.1 * fps).toInt().coerceAtLeast(1)
+ if (n < 4 * reach) return null
+ val scores = DoubleArray(2 * reach + 1)
+ for (k in -reach..reach) {
+ var s = 0.0
+ for (i in max(0, -k) until min(n, n - k)) s += a[i] * b[i + k]
+ scores[k + reach] = s
+ }
+ val best = scores.indices.maxBy { scores[it] }
+ if (scores[best] <= 0) return null
+ val shift = if (best in 1 until scores.size - 1) {
+ val l = scores[best - 1]; val c = scores[best]; val r = scores[best + 1]
+ val curve = l - 2 * c + r
+ if (curve < 0) 0.5 * (l - r) / curve else 0.0
+ } else 0.0
+ return (best - reach + shift) * 1000.0 / fps
+ }
+}
+
+/** The corpus's split and the variations of the parameters, apart from any audio so they can be tested. */
+object SegueCorpus {
+ class Row(val id: String, val title: String, val artist: String, val album: String)
+
+ /** `id|title - artist.ext` or `id|title - artist - album.ext`. */
+ fun read(file: File): List<Row> = file.readLines().filter { it.contains('|') }.map { parse(it) }
+
+ fun parse(line: String): Row {
+ val (id, name) = line.split('|', limit = 2)
+ val parts = name.substringBeforeLast('.').split(" - ").map { it.trim() }
+ return Row(id, parts.first(), parts.getOrElse(1) { "" }.ifEmpty { "unknown:$id" }, parts.getOrElse(2) { "" })
+ }
+
+ /**
+ * Whole artists and albums go to one fold, so a tuned value is never tested on the songs it was
+ * tuned on: artists sharing an album are one group, and a stable hash of the group picks its fold.
+ */
+ fun split(rows: List<Row>): Map<String, String> {
+ val parent = HashMap<String, String>()
+ fun find(x: String): String { var r = x; while (parent.getOrPut(r) { r } != r) r = parent.getValue(r); return r }
+ for (r in rows) {
+ val artist = "artist:" + r.artist.lowercase()
+ find(artist)
+ if (r.album.isNotEmpty()) parent[find("album:" + r.album.lowercase())] = find(artist)
+ }
+ return rows.associate { r -> r.id to fold(find("artist:" + r.artist.lowercase())) }
+ }
+
+ private fun fold(group: String): String {
+ val d = MessageDigest.getInstance("SHA-256").digest(group.toByteArray())
+ val x = ((d[0].toInt() and 0xff) * 256 + (d[1].toInt() and 0xff)) / 65536.0
+ return when {
+ x < SegueTuning.SPLIT_TUNING_SHARE -> "tuning"
+ x < SegueTuning.SPLIT_TUNING_SHARE + SegueTuning.SPLIT_VALIDATION_SHARE -> "validation"
+ else -> "test"
+ }
+ }
+
+ /** [base] with one numeric parameter set to [value]. */
+ fun withValue(base: SegueTuning, field: String, value: Double): SegueTuning {
+ val fields = SegueTuning::class.java.declaredFields.filter { !java.lang.reflect.Modifier.isStatic(it.modifiers) }.onEach { it.isAccessible = true }
+ val ctor = SegueTuning::class.java.declaredConstructors.first { it.parameterCount == fields.size }
+ val i = fields.indexOfFirst { it.name == field }
+ require(i >= 0) { "no parameter $field" }
+ val values = fields.map { it.get(base) }.toMutableList()
+ values[i] = when (values[i]) { is Long -> Math.round(value); is Int -> Math.round(value).toInt(); is Double -> value; else -> throw IllegalArgumentException("$field is not a number") }
+ return ctor.newInstance(*values.toTypedArray()) as SegueTuning
+ }
+
+ /** Each numeric parameter at ±[SegueTuning.STABILITY_RANGE], named `field×factor`, the others unchanged. */
+ fun variations(base: SegueTuning): List<Pair<String, SegueTuning>> {
+ val fields = SegueTuning::class.java.declaredFields.filter { !java.lang.reflect.Modifier.isStatic(it.modifiers) }.onEach { it.isAccessible = true }
+ val ctor = SegueTuning::class.java.declaredConstructors.first { it.parameterCount == fields.size }
+ val values = fields.map { it.get(base) }
+ val out = ArrayList<Pair<String, SegueTuning>>()
+ for (i in fields.indices) {
+ val v = values[i]
+ if (v !is Number) continue
+ for (f in listOf(1 - SegueTuning.STABILITY_RANGE, 1 + SegueTuning.STABILITY_RANGE)) {
+ val scaled: Any = when (v) {
+ is Long -> Math.round(v * f)
+ is Int -> Math.round(v * f).toInt()
+ else -> v.toDouble() * f
+ }
+ if (scaled == v) continue
+ out += String.format(Locale.ROOT, "%s\t%.1f", fields[i].name, f) to (ctor.newInstance(*values.toMutableList().also { it[i] = scaled }.toTypedArray()) as SegueTuning)
+ }
+ }
+ return out
+ }
+}
diff --git a/base/automix/src/test/kotlin/app/myspoti/automix/segue/SegueBenchTest.kt b/base/automix/src/test/kotlin/app/myspoti/automix/segue/SegueBenchTest.kt
new file mode 100644
index 00000000..776acecd
--- /dev/null
+++ b/base/automix/src/test/kotlin/app/myspoti/automix/segue/SegueBenchTest.kt
@@ -0,0 +1,105 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+package app.myspoti.automix.segue
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import kotlin.math.PI
+import kotlin.math.sin
+
+class SegueBenchTest {
+ private val rate = 44_100
+
+ private fun stereo(seconds: Double, f: (Int) -> Float) = FloatArray((seconds * rate).toInt() * 2) { f(it / 2) }
+
+ private fun tone(i: Int, gain: Float = 0.5f) = gain * sin(2 * PI * 440 * i / rate).toFloat()
+
+ @Test fun aSteadySignalMeasuresClean() {
+ val r = SegueMetrics.of(stereo(4.0) { tone(it) }, rate, rate, rate, 5.0, 2.0)
+ assertEquals(0.5, r.peak, 0.01)
+ assertEquals(0, r.clipped)
+ assertEquals(0.0, r.jumpDb, 0.1)
+ assertEquals(1.0, r.click, 0.1)
+ assertEquals(0.0, r.gapMs, 1.0)
+ assertEquals(5.0, r.residualMs!!, 0.0); assertEquals(2.0, r.measuredMs!!, 0.0)
+ }
+
+ @Test fun aLoudnessJumpIsMeasured() {
+ val jump = SegueMetrics.of(stereo(4.0) { tone(it, if (it < 2 * rate) 0.1f else 0.5f) }, rate, rate, rate, null, null)
+ assertEquals(14.0, jump.jumpDb, 0.2)
+ }
+
+ @Test fun clippingIsCounted() {
+ val r = SegueMetrics.of(stereo(1.0) { 1.5f }, rate / 2, rate / 4, rate, null, null)
+ assertEquals(rate * 2, r.clipped)
+ }
+
+ @Test fun aClickAtTheEdgeIsMeasured() {
+ val x = stereo(4.0) { tone(it, 0.05f) }
+ x[2 * rate] = 0.9f
+ assertTrue(SegueMetrics.click(x, rate, rate, rate) > 5)
+ }
+
+ @Test fun aSilentHoleIsMeasured() {
+ val x = stereo(4.0) { if (it in 2 * rate until 2 * rate + rate / 10) 0f else tone(it) }
+ assertEquals(100.0, SegueMetrics.longestGapMs(x, rate, 3 * rate, rate), 2.0)
+ }
+
+ @Test fun theLagOfOnsetsIsFoundWithSubFrameAccuracy() {
+ val fps = 86.0
+ fun pulses(shift: Double) = FloatArray(860) { i ->
+ var v = 0.0
+ for (k in 0 until 20) { val d = i - (k * 43 + shift); v += Math.exp(-d * d / 4) }
+ v.toFloat() - 0.2f
+ }
+ val lag = SegueMetrics.lagMs(pulses(10.0), pulses(12.0), fps)!!
+ assertEquals(2 * 1000 / fps, lag, 2.0)
+ assertEquals(-2 * 1000 / fps, SegueMetrics.lagMs(pulses(12.0), pulses(10.0), fps)!!, 2.0)
+ assertEquals(0.0, SegueMetrics.lagMs(pulses(10.0), pulses(10.0), fps)!!, 0.5)
+ assertNull(SegueMetrics.lagMs(FloatArray(4), FloatArray(4), fps))
+ assertNull(SegueMetrics.lagMs(FloatArray(860), FloatArray(860), fps))
+ }
+
+ @Test fun anArtistAndAnAlbumStayInOneFold() {
+ val rows = List(200) { SegueCorpus.Row("s$it", "t", "artist${it / 4}", "") }
+ val split = SegueCorpus.split(rows)
+ for ((_, group) in rows.groupBy { it.artist }) assertEquals(1, group.map { split[it.id] }.toSet().size)
+ val folds = split.values.groupingBy { it }.eachCount()
+ assertEquals(setOf("tuning", "validation", "test"), folds.keys)
+ assertTrue(folds.getValue("tuning") > folds.getValue("validation"))
+ val shared = listOf(SegueCorpus.Row("a", "t", "one", "album"), SegueCorpus.Row("b", "t", "two", "album"))
+ val s = SegueCorpus.split(shared)
+ assertEquals(s["a"], s["b"])
+ }
+
+ @Test fun theSplitIsStable() {
+ val rows = List(40) { SegueCorpus.Row("s$it", "t", "artist$it", "") }
+ assertEquals(SegueCorpus.split(rows), SegueCorpus.split(rows.reversed()))
+ }
+
+ @Test fun corpusNamesAreRead() {
+ val r = SegueCorpus.parse("n03|A Title - An Artist.flac")
+ assertEquals("n03", r.id); assertEquals("A Title", r.title); assertEquals("An Artist", r.artist)
+ assertEquals("unknown:n09", SegueCorpus.parse("n09|Untitled.flac").artist)
+ }
+
+ @Test fun aWhatIfChangesOnlyItsParameter() {
+ val base = SegueTuning()
+ assertEquals(base.copy(maxRateDeviationPpm = 80_000), SegueCorpus.withValue(base, "maxRateDeviationPpm", 80_000.0))
+ assertEquals(base.copy(driftMaxBeats = 0.2), SegueCorpus.withValue(base, "driftMaxBeats", 0.2))
+ }
+
+ @Test fun variationsChangeOneParameterAtATime() {
+ val base = SegueTuning()
+ val all = SegueCorpus.variations(base)
+ assertTrue(all.size > 80)
+ val v = all.first { it.first == "maxRateDeviationPpm\t1.2" }.second
+ assertEquals(48_000L, v.maxRateDeviationPpm)
+ assertEquals(base.copy(maxRateDeviationPpm = 48_000), v)
+ assertNotNull(all.first { it.first == "energySigmaDb\t0.8" })
+ for ((_, t) in all) assertNotEquals(base, t)
+ }
+}
diff --git a/base/automix/src/test/kotlin/app/myspoti/automix/segue/SeguePolicyTest.kt b/base/automix/src/test/kotlin/app/myspoti/automix/segue/SeguePolicyTest.kt
index 623a71e6..30cb3b1f 100644
--- a/base/automix/src/test/kotlin/app/myspoti/automix/segue/SeguePolicyTest.kt
+++ b/base/automix/src/test/kotlin/app/myspoti/automix/segue/SeguePolicyTest.kt
@@ -33,6 +33,7 @@ class SeguePolicyTest {
contentStart: Double = 0.0,
contentEnd: Double = duration,
barDb: Float = -10f,
+ down: Double = 0.0,
risk: (Int) -> Float = { 0f },
): TrackAnalysis {
val beat = 60 / bpm
@@ -41,7 +42,7 @@ class SeguePolicyTest {
return TrackAnalysis(duration, contentStart, contentEnd, loudness, musicKey, 1.0, bpm, grid,
if (grid) g else null, if (grid) tail ?: g else null, DoubleArray(0), DoubleArray(n) { it * 2.0 },
FloatArray(n) { barDb }, FloatArray(n) { -16f }, FloatArray(n) { -20f }, FloatArray(n), FloatArray(n), 0, stereo,
- if (grid) 0.0 else Double.NaN, if (grid) tail?.first ?: 0.0 else Double.NaN, barVocalRisk = FloatArray(n, risk),
+ if (grid) down else Double.NaN, if (grid) tail?.first ?: 0.0 else Double.NaN, barVocalRisk = FloatArray(n, risk),
audioKey = key, barBassDb = FloatArray(n) { -18f }, headPhase = phase, tailPhase = phase, headMetre = metre, tailMetre = metre)
}
@@ -225,6 +226,22 @@ class SeguePolicyTest {
assertTrue(d.plan!!.toString(), d.plan!!.outgoing.anchorUs >= 192_000_000)
}
+ @Test fun anEntryIsNeverBeforeTheSongsStart() {
+ // The grid's downbeats fall at -0.05 s, 1.95 s...: the first one in the song is the one to use.
+ val d = decide(song("a"), song("b", down = 1.95))
+ assertEquals(d.why, SegueLevel.LOCKED_LONG, d.level)
+ assertEquals(1_950_000L, d.plan!!.incoming.anchorUs)
+ val far = decide(song("a"), song("b", bpm = 100.0, down = 2.35))
+ assertEquals(far.why, SegueLevel.FILTERED, far.level)
+ assertTrue(far.plan!!.incoming.anchorUs >= 0)
+ }
+
+ @Test fun theLongestLengthThatWorksIsKept() {
+ assertEquals(t.filteredLongUs, decide(song("a"), song("b", bpm = 100.0)).plan!!.span.lengthUs)
+ assertEquals(t.filteredShortUs, decide(song("a", steadiness = 0.5), song("b", bpm = 100.0)).plan!!.span.lengthUs)
+ assertEquals(t.lockedMiddleBars, decide(song("a", metre = 0.7f), song("b", metre = 0.7f)).plan!!.span.musicalUnits)
+ }
+
@Test fun nothingStartsBeforeTheEarliestExit() {
val d = decide(song("a"), song("b"), earliest = 200_000_000)
assertTrue(d.plan!!.outgoing.anchorUs >= 200_000_000)
diff --git a/docs/automix/README.md b/docs/automix/README.md
index ad64f4cf..63dac413 100644
--- a/docs/automix/README.md
+++ b/docs/automix/README.md
@@ -135,6 +135,13 @@ Styles:
- Seek, previous, a queue change or AutoMix off: the deck is dropped (before the mix) or the song
coming in plays on at its own speed (during the mix).
+## Plan-based transitions (test)
+
+In the Mix Lab build only, a setting replaces the planner above with a policy that writes each
+transition as data, and an engine stage that plays it on the samples: see
+[segue-design.md](segue-design.md). It starts off, its numbers are unmeasured starting values, and
+every other build keeps its audio chain and its planner as they were.
+
## Known problems
- The cover now changes after a mix (the stuck cover came from the hand-over bug fixed on
diff --git a/docs/automix/segue-design.md b/docs/automix/segue-design.md
index f17402dc..acc84842 100644
--- a/docs/automix/segue-design.md
+++ b/docs/automix/segue-design.md
@@ -174,7 +174,8 @@ and the same request always gives the same plan.
| `SIMPLE_FADE` | fade | A short fade from a safe point |
| `NORMAL` | none | Plain playback. Not a failure: no effect beats a bad effect |
-Each level left behind records its cause in `SegueDecision.attempts`, outside the fingerprint.
+Each level left behind records its cause in `SegueDecision.attempts`, outside the fingerprint. Within
+a level the longest length that works is kept: a window is shortened only when it has to be.
The score is `Σ weight × reliability × note − Σ penalty × defect`. Notes and defects run from 0 to 1.
Scores compare only within a class; between classes the fallback order decides.
@@ -195,7 +196,30 @@ Scores compare only within a class; between classes the fallback order decides.
`SegueTuning.kt` documents each parameter, with its label and range, and is the only place for them.
-### Parameters that were not in the design's tables
+## Measuring
+
+No value here counts until measured on the project's corpus. The bench (`tools/automix/README.md`)
+covers the objective part, in the protocol's order:
+
+- `split` cuts the corpus by artist and album into tuning, validation and final test (60/20/20 `[I]`),
+ so a value is never tested on the songs it was tuned on.
+- `measure` checks the render's integrity first (peak, clipping, loudness jump, clicks at the edges,
+ silent holes), then compares the phase measured on the render with the plan's `residualUs`.
+- `matrix` reports each pair's level and the causes of the levels left behind, and that a second run
+ gives the same fingerprint.
+- `stability` varies each parameter by ±20 % `[I]` and lists those that change nothing: candidates
+ for removal.
+
+Still to do, as they need people or annotations: fixing thresholds by controlled degradations in blind
+listening; learning the weights from pairwise comparisons with a simple non-negative model,
+cross-validated by artist; checking the analysis against annotated beats; freezing the parameters
+before a single listen to the final test; then recording each value with its corpus, date and
+interval, and relabelling it `[M]`.
+
+The desktop render stretches with `atempo` and has no player clock, so it does not measure the phone's
+own timing; `automix.status` reports the chain's position and the deck's distance on the phone.
+
+## Parameters that were not in the design's tables
These had no value or only a word, and were added as proposals to measure. All are `[I]` unless
marked `[R]`, reused from this repository.
diff --git a/docs/cli.md b/docs/cli.md
index 46d7a3cd..8b6ccbeb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -38,6 +38,7 @@ the defaults (the beta is `-p app.myspoti`).
| `play <spotify:…> [context]`, `pause`, `resume`, `next`, `previous` | The player's own commands. |
| `nav <route>` | The open screen navigates to a route (`settings`, `extensions`, `extension/<id>`, `queue`…). |
| `automix [on\|off]` | Turns AutoMix on or off (as the setting) and prints where it stands. |
+| `automix.segue [on\|off]` | Turns the plan-based transitions on or off (Mix Lab build only; `docs/automix/segue-design.md`) and prints where they stand. |
| `automix.status` | AutoMix's state (deck, plan, position) and its journal's last 30 lines: analyses, plans, the deck's distance to its place once a second during a mix, the mix's largest gap. See `docs/automix/README.md`. |
| `automix.files <piece> <piece>…` | Plays the phone songs whose folder + title contains each piece, in that order, as the local queue (e.g. `Spotiflaccc/24`). |
| `automix.seek <ms>` | Moves in the local player's song. |
diff --git a/tools/automix/README.md b/tools/automix/README.md
index 3e1c4dbf..269c5b11 100644
--- a/tools/automix/README.md
+++ b/tools/automix/README.md
@@ -26,5 +26,18 @@ cache/read/analysis time and each pair's planning time are printed separately, f
of BLEND/CUT/FADE and blends of at least 12 bars. These are plans, not transitions heard on a phone.
The matrix does not render audio; `plan … render` remains explicit.
+Plan-based transitions (`docs/automix/segue-design.md`), from `base/`, with `-Pthreads=<n>`:
+
+```sh
+./gradlew :automix:bench -Pargs="segue <work folder> split" # tuning, validation and test folds, by artist and album, from names.txt
+./gradlew :automix:bench -Pargs="segue <work folder> matrix fold=tuning" # every ordered pair: level, causes of each level left, refusals by guard, reproducibility
+./gradlew :automix:bench -Pargs="segue <work folder> measure limit=100" # renders pairs in memory: peak, clipping, loudness jump, clicks, silent holes, phase against the plan's own expectation
+./gradlew :automix:bench -Pargs="segue <work folder> stability limit=60" # each parameter at ±20 %: how many levels and plans change, and which variations change nothing
+./gradlew :automix:bench -Pargs="segue <work folder> render s01,s02" # mix-s01-s02.wav through the same sound as the phone
+```
+
+`names.txt` has one `id|title - artist.ext` or `id|title - artist - album.ext` per song. The same
+pairs are drawn on every run. Keep the `test` fold out of any tuning.
+
The bench reads the app's Beat This model (`app/src/main/assets/automix/`) through the JVM build of
ONNX Runtime. References: `pip install beat_this` (PyTorch), then `beat_this <work folder>/*.wav`.