amethyst/desktopApp/plans/2026-10-11-desktop-video-compression-plan.md

# Desktop Video Compression Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make the composer's media-quality slider, H.265 switch and GIF→MP4 switch real on the JVM desktop by transcoding with a system `ffmpeg`, using Android's resolution/bitrate table; hide those controls when no `ffmpeg` is installed; make the "compression strips metadata" promise true even when the original is uploaded.

**Architecture:** The rules table moves from `amethyst` to `commons/commonMain` so both platforms read one source. A new `commons/jvmMain` package `service/upload/video/` runs `ffmpeg`/`ffprobe` as subprocesses (locator, encoder preference, probe, command builder, progress parser, process registry, runner). `DesktopMediaUploader` feeds every upload entry point through the compressor; `commonsUI` adapts the shared dialogs (video-aware slider stops and label, hidden controls without ffmpeg, "Upload Media").

**Tech Stack:** Kotlin Multiplatform, `java.lang.ProcessBuilder`, Jackson (already on the commons JVM classpath through quartz) for `ffprobe` JSON, kotlinx-coroutines, `kotlin.test` + `runTest`, Compose Multiplatform for the dialogs.

**Spec:** `desktopApp/plans/2026-10-11-desktop-video-compression.md`

## Global Constraints

- No new third-party dependency. `ffmpeg`/`ffprobe` are external processes found on `$PATH`, in the package-manager directories listed in spec §2, or at `${compose.application.resources.dir}/ffmpeg/<name>(.exe)`; never a working-directory-relative path. The environment variable `AMETHYST_FFMPEG_DISABLED` (any value) makes the locator report nothing — the test gate and the manual "no ffmpeg" run.
- The LOW/MEDIUM/HIGH table **including its UNKNOWN rows**, ×1.3 at ≥ 59 fps (the one deliberate change from Android, which used ≥ 60 and so missed broadcast 59.94 fps; the shared rule now moves Android too), ×0.75 for H.265, are copied **verbatim** from `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/VideoCompressionHelper.kt:112-147`. The probe-failure fallback (`:177-179`) is a separate constant: 2 000 000 bps, no resize.
- Encoder preference, exact order — H.264: `libx264, h264_videotoolbox, h264_nvenc, h264_qsv, h264_amf, h264_mf, libopenh264`; H.265: `libx265, hevc_videotoolbox, hevc_nvenc, hevc_qsv, hevc_amf, hevc_mf`. No `*_vaapi`. Candidates = available HEVC (if asked) **then** available H.264.
- Encode command (spec §2): `-map 0:v:0 -map 0:a:0? -sn -dn -map_chapters -1`, `-pix_fmt yuv420p`, `-maxrate`=`-b:v`, `-bufsize`=2×, `-c:a aac -b:a 128k`, `-map_metadata -1 -map_metadata:s -1`, `-movflags +faststart`, `-tag:v hvc1` for HEVC, `-progress pipe:1`. Remux command: `-map 0:v -map 0:a? -dn -sn -c copy -map_metadata -1 -map_metadata:s -1 -map_chapters -1 -movflags +faststart -progress pipe:1` (never `-map 0`: a MOV with a timecode data track then fails with exit 234).
- Compression progress maps to `UploadingState.Compressing` from 0.02 up to a per-path ceiling (0.20 Blossom/NIP-96, 0.40 NIP-95). No overall timeout; a stall (no progress line for 60 s) kills the process — the remux prints progress too, so it is covered the same way. A process-wide `Semaphore(1)` serialises encodes. Every live process is registered and killed by a JVM shutdown hook. Only `FfmpegProcesses` and `FfmpegProbe` switch to `Dispatchers.IO`; `FfmpegVideoCompressor` and `DesktopMediaUploader` never change dispatcher (their cancellation tests rely on `runTest` virtual time).
- Output ≥ original → the original, remuxed. Every candidate fails → the original, remuxed, plus a notice. Remux failure → the untouched original. A failed GIF conversion → the untouched GIF (never remuxed), plus the notice.
- Tests never list, create or delete files in the real `AmethystTempDir`: the compressor takes a temp-file factory and tests point it at a per-test directory.
- Every new user-visible string goes in `commonsUI/src/commonMain/composeResources/values/strings.xml`, positional format args only, no Android-style escaping.
- `com.vitorpamplona.quartz.utils.Log` lambda form; no inline fully-qualified names; production temp files only via `AmethystTempDir.createTempFile("amethyst_…", …)` (tests use their own directory, see above); delete with `File.deleteOrWarn(tag, what)`.
- `./gradlew spotlessApply` before every commit. Conventional commits. Never `--no-verify`.

## Review Focus

Inputs the spec implies that a user will hit; each has a test in the owning task:

1. A portrait phone video (height > width): the short side is the width, never upscaled, dimensions even — Task 5 `scaleFilter` test, Task 6 gated rotated-source test.
2. A 59.94 fps clip (`avg_frame_rate = 60000/1001`): gets the ×1.3 multiplier, 50 fps does not — Task 4 parser test + Task 1 multiplier test.
3. `ffprobe` missing while `ffmpeg` is present: the probe-failure constant, not a crash and not the UNKNOWN row — Task 6 test.
4. A hardware HEVC encoder listed by `-encoders` but failing at run time: the H.264 tail is reached, the bitrate recomputed without the ×0.75, and the first temp deleted — Task 3 candidate test + Task 6 retry test.
5. A packaged app launched from Finder (empty launchd PATH) with Homebrew ffmpeg: found through `/opt/homebrew/bin` — Task 2 locator test + manual sheet.

---

### Task 1: Move the rules table to `commons`

**Files:**
- Create: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/video/VideoCompressionRules.kt`
- Modify: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/CompressorQuality.kt:28-37`
- Modify: `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/VideoCompressionHelper.kt:47-107,112-147,159-180` (delete the moved types and the table; import them; keep `getVideoInfo`, `compressVideo`, the toasts)
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/video/VideoCompressionRulesTest.kt`

**Interfaces:**
- Produces (package `com.vitorpamplona.amethyst.commons.service.uploads.video`):
  - `enum class VideoStandard(val label: String)` — `UHD_4K, QHD_1440P, FHD_1080P, HD_720P, SD_480P, NHD_360P, QVGA_240P, UNKNOWN`, `toString() = label`.
  - `data class VideoResolution(val width: Int, val height: Int) { fun getStandard(): VideoStandard }` — short-side thresholds 2160/1440/1080/720/480/360/240.
  - `data class VideoInfo(val resolution: VideoResolution, val framerate: Float)`.
  - `data class CompressionRule(val shortSide: Int, val bitrateMbps: Float, val description: String) { fun getBitrateBps(framerate: Float, useH265: Boolean): Int }`.
  - `object VideoCompressionRules { fun ruleFor(quality: CompressorQuality, standard: VideoStandard): CompressionRule?; const val PROBE_FAILED_BITRATE_BPS = 2_000_000 }` — `ruleFor` looks the table up with `quality.videoLevel`, so it is null only for UNCOMPRESSED.
  - `CompressorQuality.hasVideoRule: Boolean` (constructor parameter: `VERY_LOW false, LOW true, MEDIUM true, HIGH true, VERY_HIGH false, UNCOMPRESSED true`) and `CompressorQuality.videoLevel: CompressorQuality` — a **getter** (`get() = when (this) { VERY_HIGH -> HIGH; VERY_LOW -> LOW; else -> this }`), not a constructor parameter: `VERY_LOW` is declared before `LOW`, so a constructor argument would be an illegal forward reference.

- [ ] **Step 1: Write the failing tests**

```kotlin
class VideoCompressionRulesTest {
    @Test fun standardIsKeyedOnShortSide() {
        assertEquals(VideoStandard.FHD_1080P, VideoResolution(1080, 1920).getStandard())   // portrait
        assertEquals(VideoStandard.HD_720P, VideoResolution(1280, 720).getStandard())
        assertEquals(VideoStandard.UNKNOWN, VideoResolution(200, 100).getStandard())
    }
    @Test fun tableMatchesAndroid() {
        assertEquals(CompressionRule(720, 2f, "1080p→720p, 2Mbps"), VideoCompressionRules.ruleFor(CompressorQuality.MEDIUM, VideoStandard.FHD_1080P))
        assertEquals(CompressionRule(2160, 8f, "4K→4K, 8Mbps"), VideoCompressionRules.ruleFor(CompressorQuality.HIGH, VideoStandard.UHD_4K))
        assertEquals(CompressionRule(480, 0.75f, "1080p→480p, 0.75Mbps"), VideoCompressionRules.ruleFor(CompressorQuality.LOW, VideoStandard.FHD_1080P))
        assertEquals(CompressionRule(720, 2f, "Medium quality fallback, 2Mbps"), VideoCompressionRules.ruleFor(CompressorQuality.MEDIUM, VideoStandard.UNKNOWN))
    }
    @Test fun everyRuledLevelCoversEveryStandard() {
        for (q in listOf(CompressorQuality.LOW, CompressorQuality.MEDIUM, CompressorQuality.HIGH))
            for (s in VideoStandard.entries) assertNotNull(VideoCompressionRules.ruleFor(q, s), "$q/$s")
    }
    @Test fun videoLevelMapsImageOnlyLevels() {
        assertEquals(CompressorQuality.HIGH, CompressorQuality.VERY_HIGH.videoLevel)
        assertEquals(CompressorQuality.LOW, CompressorQuality.VERY_LOW.videoLevel)
        assertEquals(CompressorQuality.MEDIUM, CompressorQuality.MEDIUM.videoLevel)
        assertEquals(VideoCompressionRules.ruleFor(CompressorQuality.HIGH, VideoStandard.UHD_4K), VideoCompressionRules.ruleFor(CompressorQuality.VERY_HIGH, VideoStandard.UHD_4K))
        assertNull(VideoCompressionRules.ruleFor(CompressorQuality.UNCOMPRESSED, VideoStandard.FHD_1080P))
    }
    @Test fun hasVideoRule() { assertEquals(listOf(false, true, true, true, false, true), CompressorQuality.entries.map { it.hasVideoRule }) }
    @Test fun bitrateMultipliers() {
        val rule = CompressionRule(1080, 4f, "")
        assertEquals(4_000_000, rule.getBitrateBps(30f, useH265 = false))
        assertEquals(5_200_000, rule.getBitrateBps(60f, useH265 = false))
        assertEquals(3_000_000, rule.getBitrateBps(30f, useH265 = true))
        assertEquals(3_900_000, rule.getBitrateBps(60f, useH265 = true))
        assertEquals(5_200_000, rule.getBitrateBps(59.94f, useH265 = false))   // Review Focus 2
        assertEquals(4_000_000, rule.getBitrateBps(50f, useH265 = false))
    }
    @Test fun probeFailureConstant() { assertEquals(2_000_000, VideoCompressionRules.PROBE_FAILED_BITRATE_BPS) }
}
```

- [ ] **Step 2: Run to verify they fail** — `./gradlew :commons:jvmTest --tests "com.vitorpamplona.amethyst.commons.service.uploads.video.*"` → unresolved symbols.
- [ ] **Step 3: Create `VideoCompressionRules.kt`** with the types in Interfaces; the table body is the three `mapOf(...)` blocks copied from `VideoCompressionHelper.kt:112-147`. Add `hasVideoRule` and `videoLevel` to `CompressorQuality`.
- [ ] **Step 4: Point Android at it.** Delete the moved declarations and `MBPS_TO_BPS_MULTIPLIER` from `VideoCompressionHelper.kt`; import the commons types; replace `compressionRules.getValue(mediaQuality).getValue(…)` with `VideoCompressionRules.ruleFor(mediaQuality, info.resolution.getStandard()) ?: return MediaCompressorResult(uri, contentType, null)` (Android never calls it at UNCOMPRESSED — `MediaCompressor.kt:67` returns before — so the branch is unreachable, but a `!!` must not be the first thing a future caller hits; the same shape `MediaCompressor.kt:94` uses); replace `2 * MBPS_TO_BPS_MULTIPLIER` with `VideoCompressionRules.PROBE_FAILED_BITRATE_BPS`.
- [ ] **Step 5: Run** `./gradlew :commons:jvmTest --tests "com.vitorpamplona.amethyst.commons.service.uploads.video.*" :amethyst:compilePlayDebugKotlin` → PASS, compiles.
- [ ] **Step 6: Commit** — `refactor(uploads): share the video compression rules through commons`

---

### Task 2: `FfmpegLocator` with package-manager paths and warm-up

**Files:**
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegLocator.kt`
- Modify: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/service/media/VideoThumbnailCache.kt:112-138` (replace the private `ffmpegBinary` lazy with `FfmpegLocator.default.ffmpeg`)
- Modify: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/app/DesktopAppModules.kt:284` (inside the existing `init { … }` block, which already starts other background work on `applicationIOScope` declared at `:151`: add `applicationIOScope.launch { FfmpegLocator.default.warmUp() }`)
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegLocatorTest.kt`

**Interfaces:**
- Produces: `class FfmpegLocator(private val runsOnPath: (binary: String) -> Boolean = ::probeOnPath, private val packageDirs: () -> List<File> = ::defaultPackageDirs, private val resourcesDir: () -> File? = { System.getProperty("compose.application.resources.dir")?.let(::File) }, private val disabled: () -> Boolean = { System.getenv("AMETHYST_FFMPEG_DISABLED") != null }) { val ffmpeg: String? by lazy; val ffprobe: String? by lazy; val available: Boolean get() = ffmpeg != null; fun warmUp() { ffmpeg; ffprobe }; companion object { val default = FfmpegLocator() } }`.
  Resolution of a name `b` (with `.exe` appended on Windows): `disabled()` → null; else `runsOnPath(b)` → `b`; else the first `dir/b` in `packageDirs()` that exists and is executable; else `resourcesDir()/ffmpeg/b` if it exists and is executable; else null. An environment variable rather than a system property because Gradle's forked test JVM and the `run` task's app JVM inherit the environment, while `-D` on the Gradle command line stays in the Gradle JVM.
  `defaultPackageDirs()`: on macOS/Linux `/opt/homebrew/bin, /usr/local/bin, /opt/local/bin`; on Windows `%ProgramFiles%\ffmpeg\bin, %LOCALAPPDATA%\Microsoft\WinGet\Links, %USERPROFILE%\scoop\shims, %ChocolateyInstall%\bin` (skipping unset variables).
  `probeOnPath` is the `-version` probe moved verbatim from `VideoThumbnailCache` (stdout/stderr discarded, 2 s wait, `destroyForcibly` on overrun, true iff exit 0).

- [ ] **Step 1: Write the failing tests** (temp dirs created in `@BeforeTest`, deleted in `@AfterTest`; executables are empty files with `setExecutable(true)`). Every `FfmpegLocator(...)` below is built through a local helper that passes `disabled = { false }` — otherwise the suite would fail when run under `AMETHYST_FFMPEG_DISABLED=1` (Task 6 Step 7, Task 11 Step 1); only `disabledIgnoresEverything` passes `{ true }`.

```kotlin
@Test fun prefersPath() { assertEquals("ffmpeg", FfmpegLocator({ true }, { emptyList() }, { null }).ffmpeg) }
@Test fun findsHomebrewStyleDirWhenPathIsBare() {        // Review Focus 5
    val bin = executable(File(pkgDir, "ffmpeg"))
    assertEquals(bin.absolutePath, FfmpegLocator({ false }, { listOf(File(dir, "missing"), pkgDir) }, { null }).ffmpeg)
}
@Test fun fallsBackToBundledExecutable() {
    val bin = executable(File(resDir, "ffmpeg/ffmpeg"))
    assertEquals(bin.absolutePath, FfmpegLocator({ false }, { emptyList() }, { resDir }).ffmpeg)
}
@Test fun nonExecutableFilesAreIgnored() {
    File(resDir, "ffmpeg/ffprobe").apply { parentFile.mkdirs(); writeText("") ; setExecutable(false) }
    assertNull(FfmpegLocator({ false }, { emptyList() }, { resDir }).ffprobe)
}
@Test fun unavailableWhenNothingExists() { assertFalse(FfmpegLocator({ false }, { emptyList() }, { null }).available) }
@Test fun disabledIgnoresEverything() { var probes = 0; val l = FfmpegLocator({ probes++; true }, { emptyList() }, { null }, disabled = { true }); assertNull(l.ffmpeg); assertNull(l.ffprobe); assertEquals(0, probes) }
@Test fun warmUpResolvesBoth() { var probes = 0; FfmpegLocator({ probes++; true }, { emptyList() }, { null }).warmUp(); assertEquals(2, probes) }
```

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement** `FfmpegLocator.kt`; switch `VideoThumbnailCache.runFfmpeg` to `FfmpegLocator.default.ffmpeg` and delete its lazy; add the warm-up launch in `DesktopAppModules`' `init`.
- [ ] **Step 4: Run** `./gradlew :commons:jvmTest --tests "*FfmpegLocatorTest" :desktopApp:compileKotlin` → PASS, compiles.
- [ ] **Step 5: Commit** — `refactor(desktop): FfmpegLocator finds package-manager installs and warms up at start`

---

### Task 3: `FfmpegEncoders` — parse `-encoders`, pick by preference

**Files:**
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegEncoders.kt`
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegEncodersTest.kt`

**Interfaces:**
- Produces: `object FfmpegEncoders { val H264: List<String>; val H265: List<String>; fun parseAvailable(encodersOutput: String): Set<String>; fun candidates(available: Set<String>, useH265: Boolean): List<String>; fun isHevc(encoder: String): Boolean = encoder in H265; suspend fun listAvailable(ffmpeg: String): Set<String> }`. `candidates` = `(if (useH265) H265.filter { it in available } else emptyList()) + H264.filter { it in available }`. `listAvailable` runs `ffmpeg -hide_banner -encoders` on `Dispatchers.IO` (stderr discarded, 5 s cap) and parses stdout; the result is memoized per `ffmpeg` path in a `ConcurrentHashMap` so each upload does not spawn a process (a failed run is not cached — an empty set is returned and the next call retries).

- [ ] **Step 1: Write the failing tests** (real `-encoders` line format: six flag characters, name, description)

```kotlin
private val GPL = """
Encoders:
 V..... = Video
 ------
 V....D libx264              libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (codec h264)
 V....D h264_videotoolbox    VideoToolbox H.264 Encoder (codec h264)
 V....D libx265              libx265 H.265 / HEVC (codec hevc)
 V....D hevc_nvenc           NVIDIA NVENC hevc encoder (codec hevc)
 V....D h264_vaapi           H.264/AVC (VAAPI) (codec h264)
 A....D aac                  AAC (Advanced Audio Coding)
""".trimIndent()
private val LGPL = GPL.lines().filterNot { "libx26" in it }.joinToString("\n") + "\n V....D libopenh264          OpenH264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (codec h264)"

@Test fun parsesNamesOnly() { assertEquals(setOf("libx264", "h264_videotoolbox", "libx265", "hevc_nvenc", "h264_vaapi", "aac"), FfmpegEncoders.parseAvailable(GPL)) }
@Test fun vaapiIsNeverACandidate() { assertFalse("h264_vaapi" in FfmpegEncoders.candidates(FfmpegEncoders.parseAvailable(GPL), false)) }
@Test fun gplBuildPrefersX264() { assertEquals(listOf("libx264", "h264_videotoolbox"), FfmpegEncoders.candidates(FfmpegEncoders.parseAvailable(GPL), useH265 = false)) }
@Test fun lgplBuildFallsBackThroughHardwareToOpenH264() { assertEquals(listOf("h264_videotoolbox", "libopenh264"), FfmpegEncoders.candidates(FfmpegEncoders.parseAvailable(LGPL), useH265 = false)) }
@Test fun hevcCandidatesComeFirstThenH264() {              // Review Focus 4
    assertEquals(listOf("libx265", "hevc_nvenc", "libx264", "h264_videotoolbox"), FfmpegEncoders.candidates(FfmpegEncoders.parseAvailable(GPL), useH265 = true))
    assertEquals(listOf("hevc_nvenc", "h264_videotoolbox", "libopenh264"), FfmpegEncoders.candidates(FfmpegEncoders.parseAvailable(LGPL), useH265 = true))
}
@Test fun isHevc() { assertTrue(FfmpegEncoders.isHevc("hevc_videotoolbox")); assertFalse(FfmpegEncoders.isHevc("libx264")) }
```

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement.** Parse only the lines **after** the ` ------` separator (the legend above it — ` V..... = Video`, ` .F.... = Frame-level multithreading` — has the same six-character shape and a naive regex captures `=` three times on a real ffmpeg 9 listing), each with `Regex("""^\s*[VAS][.F][.S][.X][.B][.D]\s+([A-Za-z0-9_]+)""")`. The `GPL` fixture above keeps its legend line and separator on purpose so `parsesNamesOnly` proves this.
- [ ] **Step 4: Run** `./gradlew :commons:jvmTest --tests "*FfmpegEncodersTest"` → PASS.
- [ ] **Step 5: Commit** — `feat(uploads): encoder preference list for ffmpeg video compression`

---

### Task 4: `FfmpegProbe` — `ffprobe` JSON → `VideoInfo`, duration, HDR

**Files:**
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegProbe.kt`
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfprobeOutputParserTest.kt`

**Interfaces:**
- Consumes: `VideoInfo`, `VideoResolution` (Task 1).
- Produces: `data class ProbeResult(val info: VideoInfo, val durationSeconds: Double?, val isHdr: Boolean)`; `object FfprobeOutputParser { fun parse(json: String): ProbeResult? }`; `open class FfmpegProbe(private val ffprobe: String?) { open suspend fun probe(file: File): ProbeResult? }` (open so Task 6's test can fake it) running, on `Dispatchers.IO`, `ffprobe -v error -select_streams V:0 -show_entries stream=width,height,avg_frame_rate,color_transfer -show_entries format=duration -of json <file>` (10 s cap); null when `ffprobe` is null, the process fails, or parsing fails. `isHdr` = `color_transfer` is `smpte2084` or `arib-std-b67`.

- [ ] **Step 1: Write the failing tests**

```kotlin
private const val JSON = """{"streams":[{"width":1920,"height":1080,"avg_frame_rate":"60000/1001","color_transfer":"bt709"}],"format":{"duration":"30.528000"}}"""
@Test fun parsesDimensionsFpsAndDuration() {
    val r = FfprobeOutputParser.parse(JSON)!!
    assertEquals(VideoResolution(1920, 1080), r.info.resolution)
    assertEquals(59.94f, r.info.framerate, 0.01f)                               // Review Focus 2
    assertEquals(30.528, r.durationSeconds!!, 0.001); assertFalse(r.isHdr)
}
@Test fun hdrTransfers() {
    for (t in listOf("smpte2084", "arib-std-b67")) assertTrue(FfprobeOutputParser.parse("""{"streams":[{"width":10,"height":10,"avg_frame_rate":"30/1","color_transfer":"$t"}],"format":{}}""")!!.isHdr, t)
}
@Test fun missingDurationAndTransferAreTolerated() { val r = FfprobeOutputParser.parse("""{"streams":[{"width":10,"height":10,"avg_frame_rate":"30/1"}],"format":{}}""")!!; assertNull(r.durationSeconds); assertFalse(r.isHdr) }
@Test fun noVideoStreamIsNull() { assertNull(FfprobeOutputParser.parse("""{"streams":[],"format":{"duration":"1"}}""")) }
@Test fun garbageIsNull() { assertNull(FfprobeOutputParser.parse("not json")) }
@Test fun zeroDenominatorFpsIsZero() { assertEquals(0f, FfprobeOutputParser.parse("""{"streams":[{"width":10,"height":10,"avg_frame_rate":"0/0"}],"format":{}}""")!!.info.framerate) }
```

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement** with Jackson's `ObjectMapper().readTree(json)`; `avg_frame_rate` is `num/den` → `num.toFloat() / den` (0 when den is 0).
- [ ] **Step 4: Run** `./gradlew :commons:jvmTest --tests "*FfprobeOutputParserTest"` → PASS.
- [ ] **Step 5: Commit** — `feat(uploads): ffprobe-based video info for desktop compression`

---

### Task 5: `FfmpegCommandBuilder` and `FfmpegProgressParser`

**Files:**
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegCommandBuilder.kt`
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegProgressParser.kt`
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegCommandBuilderTest.kt`, `…/FfmpegProgressParserTest.kt`

**Interfaces:**
- Produces:
  - `object FfmpegCommandBuilder { fun scaleFilter(shortSide: Int?): String; fun encode(ffmpeg: String, input: File, output: File, encoder: String, bitrateBps: Int, shortSide: Int?): List<String>; fun remux(ffmpeg: String, input: File, output: File): List<String> }`.
    `scaleFilter(S)` = `scale='if(gt(iw,ih),-2,trunc(min(S,iw)/2)*2)':'if(gt(iw,ih),trunc(min(S,ih)/2)*2,-2)'`; `scaleFilter(null)` = `scale=trunc(iw/2)*2:trunc(ih/2)*2`.
    `encode` = `[ffmpeg, -hide_banner, -loglevel, error, -nostdin, -y, -i, input, -map, 0:v:0, -map, 0:a:0?, -sn, -dn, -map_chapters, -1, -c:v, encoder, -b:v, N, -maxrate, N, -bufsize, 2N, -pix_fmt, yuv420p, -vf, scaleFilter(shortSide), -c:a, aac, -b:a, 128k, -map_metadata, -1, -map_metadata:s, -1, -movflags, +faststart, (-tag:v, hvc1 when FfmpegEncoders.isHevc(encoder)), -progress, pipe:1, output]`.
    `remux` = `[ffmpeg, -hide_banner, -loglevel, error, -nostdin, -y, -i, input, -map, 0:v, -map, 0:a?, -dn, -sn, -c, copy, -map_metadata, -1, -map_metadata:s, -1, -map_chapters, -1, -movflags, +faststart, -progress, pipe:1, output]` — video and audio only (a MOV timecode/data track makes `-map 0` fail with exit 234), and `-progress` so the stall watchdog sees output.
  - `class FfmpegProgressParser(private val durationSeconds: Double?) { fun onLine(line: String): Double? }` — `out_time_us=<n>` → `(n / 1e6 / duration).coerceIn(0.0, 1.0)` (null when duration is null or ≤ 0, or the value is not a number such as `N/A`); `progress=end` → `1.0`; anything else → null.

- [ ] **Step 1: Write the failing tests**

```kotlin
// FfmpegCommandBuilderTest
@Test fun portraitLimitsWidthAndKeepsEven() {             // Review Focus 1
    assertEquals("scale='if(gt(iw,ih),-2,trunc(min(720,iw)/2)*2)':'if(gt(iw,ih),trunc(min(720,ih)/2)*2,-2)'", FfmpegCommandBuilder.scaleFilter(720))
}
@Test fun noRuleOnlyEvensDimensions() { assertEquals("scale=trunc(iw/2)*2:trunc(ih/2)*2", FfmpegCommandBuilder.scaleFilter(null)) }
@Test fun h264EncodeCommand() {
    val cmd = FfmpegCommandBuilder.encode("ffmpeg", File("in.mov"), File("out.mp4"), "libx264", 4_000_000, 1080)
    assertEquals(listOf("-map", "0:v:0", "-map", "0:a:0?", "-sn", "-dn", "-map_chapters", "-1"), cmd.subList(cmd.indexOf("-map"), cmd.indexOf("-map") + 8))
    assertEquals(listOf("-c:v", "libx264", "-b:v", "4000000", "-maxrate", "4000000", "-bufsize", "8000000"), cmd.subList(cmd.indexOf("-c:v"), cmd.indexOf("-c:v") + 8))
    assertFalse("-tag:v" in cmd); assertTrue(cmd.containsAll(listOf("-movflags", "+faststart", "-map_metadata:s", "-progress", "pipe:1"))); assertEquals("out.mp4", cmd.last())
}
@Test fun hevcEncodeTagsHvc1() { val cmd = FfmpegCommandBuilder.encode("ffmpeg", File("a"), File("b"), "hevc_videotoolbox", 1, null); assertEquals("hvc1", cmd[cmd.indexOf("-tag:v") + 1]) }
@Test fun remuxCopiesVideoAndAudioOnlyAndStrips() {
    val cmd = FfmpegCommandBuilder.remux("ffmpeg", File("a"), File("b"))
    assertEquals(listOf("-map", "0:v", "-map", "0:a?", "-dn", "-sn", "-c", "copy", "-map_metadata", "-1", "-map_metadata:s", "-1", "-map_chapters", "-1", "-movflags", "+faststart", "-progress", "pipe:1", "b"), cmd.subList(cmd.indexOf("-map"), cmd.size))
    assertFalse("-c:v" in cmd); assertFalse("0" in cmd)   // never `-map 0`
}

// FfmpegProgressParserTest
@Test fun fractionOfDuration() { assertEquals(0.5, FfmpegProgressParser(10.0).onLine("out_time_us=5000000")!!, 1e-9) }
@Test fun clampsOvershoot() { assertEquals(1.0, FfmpegProgressParser(10.0).onLine("out_time_us=99000000")) }
@Test fun endIsOne() { assertEquals(1.0, FfmpegProgressParser(null).onLine("progress=end")) }
@Test fun notAvailableAndOtherKeysAreNull() { val p = FfmpegProgressParser(10.0); assertNull(p.onLine("out_time_us=N/A")); assertNull(p.onLine("frame=12")); assertNull(FfmpegProgressParser(null).onLine("out_time_us=5")) }
```

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement both files.** — [ ] **Step 4: Run** `./gradlew :commons:jvmTest --tests "*Ffmpeg*"` → PASS.
- [ ] **Step 5: Commit** — `feat(uploads): ffmpeg command builder and progress parser`

---

### Task 6: `FfmpegVideoCompressor` — the runner

**Files:**
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/VideoCompressor.kt` (interface + result)
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegProcesses.kt` (runner + registry + shutdown hook)
- Create: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegVideoCompressor.kt`
- Create: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/notices/UploadNotices.kt`
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/upload/video/FfmpegVideoCompressorTest.kt`, `…/FfmpegProcessesTest.kt` (real child process, no ffmpeg), `…/FfmpegVideoCompressorFfmpegTest.kt` (gated)

**Interfaces:**
- Consumes: Tasks 1–5; `AmethystTempDir.createTempFile`, `File.deleteOrWarn`, `UserNotice`.
- Produces:
  - `sealed interface UploadNotice : UserNotice { data class VideoCompressionFailed(val reason: String?) : UploadNotice; data object HevcUnavailable : UploadNotice; data object HdrSource : UploadNotice }` (commonMain).
  - `sealed interface VideoCompressionResult { data class Compressed(val file: File, val notices: List<UserNotice> = emptyList()) : VideoCompressionResult; data class Original(val stripped: File?, val notices: List<UserNotice> = emptyList()) : VideoCompressionResult; data object TooBig : VideoCompressionResult }` — `stripped` is a remuxed temp (caller deletes) or null when remux was impossible.
  - `interface VideoCompressor { val available: Boolean; suspend fun probe(source: File): VideoInfo?; suspend fun compress(source: File, quality: CompressorQuality, useH265: Boolean, maxBytes: Long? = null, onProgress: (Double) -> Unit): VideoCompressionResult; suspend fun convertGif(source: File, onProgress: (Double) -> Unit): VideoCompressionResult; suspend fun strip(source: File): File? }` — `probe` is what the slider label uses (null when `ffprobe` is missing or the file cannot be read); `strip` is the remux alone (null when unavailable or failed).
  - `fun interface ProcessRunner { suspend fun run(command: List<String>, onStdoutLine: (String) -> Unit, stallTimeoutMs: Long): ProcessOutcome }`, `data class ProcessOutcome(val exitCode: Int, val stderrTail: String)`.
  - `object FfmpegProcesses : ProcessRunner` — the real runner, the only place besides `FfmpegProbe` that uses `Dispatchers.IO`: `ProcessBuilder`, stdout read line by line, stderr drained on its own thread with the last 2 KB kept, no stdout line for `stallTimeoutMs` → `destroyForcibly()` and exit code `-1`, coroutine cancellation → `destroyForcibly()`; every started `Process` is added to `val live = ConcurrentHashMap.newKeySet<Process>()` (internal, so the test can assert it is empty) and removed on exit; `init` registers `Runtime.getRuntime().addShutdownHook` that `destroyForcibly()`s every live one. Exposes `val encodeGate = Semaphore(1)` (kotlinx) for the compressor.
  - `class FfmpegVideoCompressor(private val locator: FfmpegLocator = FfmpegLocator.default, private val encoders: suspend (ffmpeg: String) -> Set<String> = FfmpegEncoders::listAvailable, private val probe: (ffprobe: String?) -> FfmpegProbe = ::FfmpegProbe, private val stallTimeoutMs: Long = 60_000, private val runner: ProcessRunner = FfmpegProcesses, private val gate: Semaphore = FfmpegProcesses.encodeGate, private val tempFile: () -> File = { AmethystTempDir.createTempFile("amethyst_video_", ".mp4") }) : VideoCompressor`. The class never calls `withContext`; it runs on the caller's dispatcher.

Algorithm of `compress` (not determined by the signature and tests):
1. `ffmpeg = locator.ffmpeg ?: return Original(null)`.
2. `probed = probe(locator.ffprobe).probe(source)`; `rule = probed?.let { VideoCompressionRules.ruleFor(quality, it.info.resolution.getStandard()) }`; `shortSide = rule?.shortSide`; `fps = probed?.info?.framerate ?: 30f`; `notices` starts with `HdrSource` when `probed?.isHdr == true`.
3. `maxBytes` given and `probed?.durationSeconds` known: `estimate = ((bitrateFor(hevc = useH265) + 128_000) / 8.0) * duration`; `estimate > maxBytes` → `TooBig`.
4. `candidates = FfmpegEncoders.candidates(encoders(ffmpeg), useH265)`; empty → `fail("no encoder")`.
5. Under `gate.withPermit`, for each candidate: `hevc = isHevc(candidate)`, `bitrate = rule?.getBitrateBps(fps, hevc) ?: PROBE_FAILED_BITRATE_BPS`; then `var out: File? = null; try { out = tempFile(); run encode(...) feeding FfmpegProgressParser(probed?.durationSeconds) into onProgress; exit 0 → stop; else delete out, keep stderrTail, continue } catch (e: CancellationException) { withContext(NonCancellable) { out?.deleteOrWarn(...) }; throw e }` — `out` is created **inside** the `try` so a `tempFile()` that throws leaves nothing behind.
6. No success → `fail(lastStderrTail)` where `fail(reason)` = `Original(strip(source), notices + VideoCompressionFailed(reason))`.
7. `out.length() >= source.length()` → delete `out`, `Original(strip(source), notices)`.
8. `useH265 && !hevcOfTheWinner` → `notices += HevcUnavailable`. `Compressed(out, notices)`.

`convertGif` = steps 1, 2 (rule = MEDIUM row for the GIF's standard, `shortSide = null` so the source size is kept), 4–8 with `useH265 = false`, no size-vs-original rule (an MP4 is routinely bigger than a GIF; the point is playability), and failure = `Original(null, notices + VideoCompressionFailed(reason))` — a GIF is never remuxed. `probe(source)` = `probe(locator.ffprobe).probe(source)?.info`. `strip(source)` runs `remux` into `tempFile()`, returning the file on exit 0, else deleting it and returning null.

- [ ] **Step 1: Write the failing unit tests** with a fake `ProcessRunner` that records commands, writes the scripted progress lines, creates the output file (last argument) with the scripted byte count, and returns a scripted exit code per call:

Every test is `= runTest { … }` — `compress`, `convertGif` and `strip` are `suspend`.

```kotlin
@Test fun retriesNextEncoderWhenFirstFails() = runTest {            // Review Focus 4
    val runner = FakeRunner(exitCodes = listOf(1, 0), outputBytes = 10)
    val r = compressor(runner, encoders = setOf("hevc_nvenc", "libx264")).compress(source(1000), CompressorQuality.HIGH, useH265 = true) {}
    assertIs<VideoCompressionResult.Compressed>(r)
    assertEquals(listOf("hevc_nvenc", "libx264"), runner.commands.map { it[it.indexOf("-c:v") + 1] })
    assertEquals(listOf("3000000", "4000000"), runner.commands.map { it[it.indexOf("-b:v") + 1] })   // ×0.75 only for the HEVC attempt
    assertEquals(listOf(UploadNotice.HevcUnavailable), r.notices)
    assertEquals(1, tempVideos().size)                                            // the failed temp is gone
}
@Test fun allEncodersFailingRemuxesOriginalWithNotice() = runTest {
    val runner = FakeRunner(exitCodes = listOf(1, 0), stderr = "boom", outputBytes = 10)                  // 2nd call is the remux
    val r = compressor(runner, setOf("libx264")).compress(source(1000), CompressorQuality.HIGH, false) {}
    assertEquals(listOf(UploadNotice.VideoCompressionFailed("boom")), (r as VideoCompressionResult.Original).notices)
    assertNotNull(r.stripped); assertTrue("copy" in runner.commands[1])
}
@Test fun largerOutputIsDiscardedAndOriginalRemuxed() = runTest {
    val runner = FakeRunner(exitCodes = listOf(0, 0), outputBytes = 5000)
    val r = compressor(runner, setOf("libx264")).compress(source(1000), CompressorQuality.HIGH, false) {}
    assertIs<VideoCompressionResult.Original>(r); assertNotNull(r.stripped); assertEquals(1, tempVideos().size)
}
@Test fun remuxFailureYieldsNullStripped() = runTest { val r = compressor(FakeRunner(listOf(0, 1), outputBytes = 5000), setOf("libx264")).compress(source(1000), CompressorQuality.HIGH, false) {}; assertNull((r as VideoCompressionResult.Original).stripped); assertTrue(tempVideos().isEmpty()) }
@Test fun hdrSourceIsNoticed() = runTest { val r = compressor(FakeRunner(listOf(0), outputBytes = 10), setOf("libx264"), hdr = true).compress(source(1000), CompressorQuality.HIGH, false) {}; assertEquals(listOf(UploadNotice.HdrSource), (r as VideoCompressionResult.Compressed).notices) }
@Test fun missingFfprobeUsesProbeFailureFallback() = runTest {     // Review Focus 3
    val runner = FakeRunner(listOf(0), outputBytes = 10)
    compressor(runner, setOf("libx264"), ffprobe = null).compress(source(1000), CompressorQuality.HIGH, false) {}
    val cmd = runner.commands.single(); assertEquals("2000000", cmd[cmd.indexOf("-b:v") + 1]); assertEquals("scale=trunc(iw/2)*2:trunc(ih/2)*2", cmd[cmd.indexOf("-vf") + 1])
}
@Test fun probeExposesInfo() = runTest { assertEquals(VideoResolution(1920, 1080), compressor(FakeRunner(listOf()), setOf("libx264")).probe(source(1))!!.resolution); assertNull(compressor(FakeRunner(listOf()), setOf("libx264"), ffprobe = null).probe(source(1))) }
@Test fun veryHighEncodesAsHigh() = runTest { val runner = FakeRunner(listOf(0), outputBytes = 10); compressor(runner, setOf("libx264")).compress(source(1000), CompressorQuality.VERY_HIGH, false) {}; assertEquals("4000000", runner.commands.single().let { it[it.indexOf("-b:v") + 1] }) }
@Test fun nip95EstimateRefusesEarly() = runTest { val runner = FakeRunner(listOf(0), outputBytes = 10); assertEquals(VideoCompressionResult.TooBig, compressor(runner, setOf("libx264"), duration = 30.0).compress(source(1000), CompressorQuality.HIGH, false, maxBytes = 80_000) {}); assertTrue(runner.commands.isEmpty()) }
@Test fun progressIsForwarded() = runTest { val seen = mutableListOf<Double>(); compressor(FakeRunner(listOf(0), outputBytes = 10, progressLines = listOf("out_time_us=1000000", "out_time_us=N/A", "progress=end")), setOf("libx264"), duration = 2.0).compress(source(1000), CompressorQuality.HIGH, false) { seen += it }; assertEquals(listOf(0.5, 1.0), seen) }
@Test fun gifKeepsSizeAndIgnoresSizeRule() = runTest {
    val runner = FakeRunner(listOf(0), outputBytes = 5000)
    val r = compressor(runner, setOf("libx264")).convertGif(source(1000)) {}
    assertIs<VideoCompressionResult.Compressed>(r); val cmd = runner.commands.single(); assertEquals("scale=trunc(iw/2)*2:trunc(ih/2)*2", cmd[cmd.indexOf("-vf") + 1]); assertEquals("2000000", cmd[cmd.indexOf("-b:v") + 1])   // MEDIUM row for 1080p
}
@Test fun gifFailureIsNeverRemuxed() = runTest {
    val runner = FakeRunner(listOf(1), stderr = "bad gif", outputBytes = 0)
    val r = compressor(runner, setOf("libx264")).convertGif(source(1000)) {}
    assertEquals(VideoCompressionResult.Original(null, listOf(UploadNotice.VideoCompressionFailed("bad gif"))), r)
    assertEquals(1, runner.commands.size); assertTrue(tempVideos().isEmpty())   // no remux call, no temp left
}
@Test fun encodesRunOneAtATime() = runTest {
    val runner = FakeRunner(listOf(0, 0), outputBytes = 10, delayMs = 50, recordConcurrency = true)
    val c = compressor(runner, setOf("libx264"))
    listOf(async { c.compress(source(1000), CompressorQuality.HIGH, false) {} }, async { c.compress(source(1000), CompressorQuality.HIGH, false) {} }).awaitAll()
    assertEquals(1, runner.maxConcurrent)
}
@Test fun cancellationDeletesTemp() = runTest { val runner = FakeRunner(listOf(0), outputBytes = 10, delayMs = 10_000); val job = launch { compressor(runner, setOf("libx264")).compress(source(1000), CompressorQuality.HIGH, false) {} }; advanceTimeBy(100); job.cancelAndJoin(); assertTrue(tempVideos().isEmpty()) }
@Test fun noFfmpegIsOriginalUnstripped() = runTest { assertEquals(VideoCompressionResult.Original(null), FfmpegVideoCompressor(locator = FfmpegLocator({ false }, { emptyList() }, { null })).compress(source(1), CompressorQuality.HIGH, false) {}) }
```

`compressor(runner, encoders, ffprobe = "ffprobe", duration = 30.0, hdr = false)` builds `FfmpegVideoCompressor(locator = FfmpegLocator({ true }, { emptyList() }, { null }, disabled = { false }), encoders = { encoders }, probe = { FakeProbe(ffprobe, duration, hdr) }, runner = runner, gate = Semaphore(1), tempFile = { File.createTempFile("amethyst_video_", ".mp4", tempDir) })`, where `FakeProbe` returns a 1920×1080 @ 30 fps `ProbeResult` unless `ffprobe` is null; `tempDir` is a fresh directory per test (`@BeforeTest` creates it, `@AfterTest` deletes it recursively) and `tempVideos()` lists its `amethyst_video_*` entries; `source(bytes)` writes a file of that size into `tempDir` under a different prefix (`src_`). The real `AmethystTempDir` is never read or written by this test. `FakeRunner.delayMs` is a `kotlinx.coroutines.delay`, which is why `cancellationDeletesTemp` and `encodesRunOneAtATime` work under `runTest` virtual time — and why the compressor must not switch dispatcher.

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement** the four source files.
- [ ] **Step 4: Run** `./gradlew :commons:jvmTest --tests "*FfmpegVideoCompressorTest"` → PASS.
- [ ] **Step 5: Write `FfmpegProcessesTest.kt`** against the real runner with a real child process, no ffmpeg involved (`sleep` on macOS/Linux, `timeout /t` on Windows — pick by `os.name`):
  - `stalledChildIsKilledAndUnregistered` = `runTest`-free (`runBlocking`, real time): `FfmpegProcesses.run(listOf("sleep", "30"), {}, stallTimeoutMs = 200)` returns within a few seconds with `exitCode == -1`, and `FfmpegProcesses.live.isEmpty()` afterwards.
  - `exitAndStderrAreForwarded`: `run(listOf("sh", "-c", "echo out; echo err 1>&2; exit 3"), …, 5_000)` → `exitCode == 3`, `stderrTail.trim() == "err"`, the stdout callback saw `out` (on Windows use `cmd /c`).
  - `cancellationKillsTheChild` (`runBlocking`): launch `run(listOf("sleep", "30"), {}, 60_000)`, cancel after 100 ms, join → `live.isEmpty()`.
- [ ] **Step 6: Write the gated tests** in `FfmpegVideoCompressorFfmpegTest.kt`; every test starts with `if (!ffmpegForTests()) return`, where `ffmpegForTests()` = `FfmpegLocator.default.ffmpeg != null && FfmpegLocator.default.ffprobe != null && "libx264" in runBlocking { FfmpegEncoders.listAvailable(ffmpeg) }` (the size and bitrate assertions below were measured with x264; an LGPL build encodes differently). Fixtures made with the real binary into a temp dir:
  - `noisy.mp4`: `ffmpeg -f lavfi -i "color=c=gray:s=1920x1080:r=30,noise=alls=100:allf=t+u" -f lavfi -i sine -t 2 -shortest -pix_fmt yuv420p -c:v libx264 -crf 18 -preset ultrafast -metadata title=secret noisy.mp4` (high-entropy, ~90 MB, so every encode is smaller — spec §5; `noise` is a filter and needs the `color` source in front).
  - `easy.mp4`: `ffmpeg -f lavfi -i testsrc=size=1920x1080:rate=30 -t 2 -pix_fmt yuv420p -metadata title=secret easy.mp4` (55 KB; every encode is larger — HIGH measured 181 KB — so the result is the remuxed original, which is what the `title` assertion checks).
  - `rotated.mp4`: `ffmpeg -display_rotation 90 -i noisy.mp4 -c copy rotated.mp4` — from **`noisy`**, so the encode is kept (`easy`'s would be discarded for the remux, which still carries the rotation side data). ffprobe shows `side_data_list: [{rotation: 90}]`; `-metadata:s:v:0 rotate=90` writes nothing on ffmpeg 9.
  - `tc.mov`: `ffmpeg -f lavfi -i testsrc=size=1920x1080:rate=30 -t 2 -pix_fmt yuv420p -timecode 00:00:00:00 -metadata location=+48.2082+016.3738/ -metadata title=secret tc.mov` (one video stream plus a `data` timecode track — the shape iPhones write; `-map 0 -c copy` to MP4 exits 234 on it).
  - Asserting with a small JSON read of `ffprobe -v error -select_streams V:0 -show_entries stream=width,height,codec_name,bit_rate:stream_side_data=rotation:format_tags -of json`:
    - `compress(noisy, HIGH, false)` → `Compressed`, 1920×1080, `bit_rate ≤ 4_000_000 * (1 + 2 / 2.0)` (the VBV bound with `bufsize = 2b` on a 2 s clip — a short clip legitimately bursts above the target), `format_tags` has no `title`.
    - `compress(noisy, LOW, false)` → short side 480 (854×480), and its `bit_rate` < the HIGH output's.
    - `compress(noisy, MEDIUM, true)` → `Compressed`; when `HevcUnavailable` is not in `notices`, `codec_name == hevc`.
    - `compress(easy, HIGH, false)` → `Original` with non-null `stripped`, `stripped.length() < easy.length() + 4096`, no `title` tag (the source has one).
    - `compress(rotated, HIGH, false)` → `Compressed`, width 1080, height 1920 and no `side_data_list` on the output stream (measured 215 KB).
    - `strip(tc)` → non-null; `ffprobe -show_entries stream=codec_type:format_tags` on it shows exactly one stream (`video`) and neither `title` nor `location`.
- [ ] **Step 7: Run** with ffmpeg installed → PASS; `AMETHYST_FFMPEG_DISABLED=1 ./gradlew :commons:jvmTest --tests "*Ffmpeg*"` → gated tests return early, the unit tests and `FfmpegProcessesTest` PASS (a bare `PATH` is not a valid gate: the locator finds Homebrew by design).
- [ ] **Step 8: Commit** — `feat(uploads): FfmpegVideoCompressor with encoder fallback, remux strip and stall watchdog`

---

### Task 7: Notice plumbing and wording

**Files:**
- Create: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/app/ForwardingNoticeSink.kt`
- Modify: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/app/DesktopAccountViewModelHost.kt:77` (add `val notices = ForwardingNoticeSink()` beside it)
- Modify: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/app/DesktopAppRoot.kt:70-79`
- Modify: `commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/notices/ui/UserNoticeText.kt` (add the `UploadNotice` branches beside `NoteActionNotice`)
- Modify: `commonsUI/src/commonMain/composeResources/values/strings.xml` (after `media_compression_preview_tap_compressed`)
- Test: `desktopApp/src/jvmTest/kotlin/com/vitorpamplona/amethyst/desktop/app/ForwardingNoticeSinkTest.kt`

**Interfaces:**
- Produces: `class ForwardingNoticeSink : UserNoticeSink { @Volatile var target: UserNoticeSink? = null; override fun notify(notice: UserNotice) { target?.notify(notice) ?: Log.w(TAG) { "No sink for $notice" } } }`; `DesktopAppRoot.createAccountViewModel` does `.also { host.notices.target = it.toastManager }` on the `AccountViewModel` it builds.
- Strings (exact copy):
  - `video_compression_failed_title` = `Video compression failed`
  - `video_compression_failed_message` = `The original file is being uploaded instead.`
  - `video_compression_hevc_unavailable_title` = `H.265 not available`
  - `video_compression_hevc_unavailable_message` = `ffmpeg has no working HEVC encoder on this computer, so the video was encoded as H.264.`
  - `video_compression_hdr_title` = `HDR video`
  - `video_compression_hdr_message` = `Compressed HDR video looks flat. Choose Uncompressed to keep the original colours.`
- Wording in `UserNoticeText.kt`: `VideoCompressionFailed` → title/message above with `reason` as the details line the way `SignerNotice.Failed` passes its cause; `HevcUnavailable` and `HdrSource` → their title/message.

- [ ] **Step 1: Write the failing test** — `notify` before a target is set does not throw; after `target = recording sink`, the notice arrives.
- [ ] **Step 2: Run to verify it fails.** — [ ] **Step 3: Implement** the sink, the host property, the root wiring, the strings, the wording.
- [ ] **Step 4: Run** `./gradlew :desktopApp:test --tests "*ForwardingNoticeSinkTest" :commonsUI:compileKotlinJvm` → PASS, compiles.
- [ ] **Step 5: Commit** — `feat(desktop): route typed upload notices to the toast manager`

---

### Task 8: `DesktopMediaUploader` compresses, strips and probes video

**Files:**
- Modify: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/MediaUploader.kt:100-102` (add the two members before `displayName`) and `:126` (`UnavailableMediaUploader`: `videoCompression = Unsupported`)
- Create: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/VideoCompressionSupport.kt`
- Modify: `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/AndroidMediaUploader.kt:79` (`override val videoCompression = VideoCompressionSupport.Supported`)
- Modify: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/app/DesktopMediaUploader.kt` (constructor `:78-81`, `upload` `:115-158`, `uploadEncrypted` `:160-206`, `preparePayload` `:220-236`, `nip95` `:238-269`, `nip96` `:271-313`, `compressIfNeeded` `:351-358`, `stripMetadata` `:413-420`)
- Modify: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/app/DesktopAccountViewModelHost.kt:77`
- Test: `desktopApp/src/jvmTest/kotlin/com/vitorpamplona/amethyst/desktop/app/DesktopMediaUploaderVideoTest.kt`

**Interfaces:**
- Consumes: `VideoCompressor` (with `probe`), `VideoCompressionResult`, `FfmpegVideoCompressor` (Task 6), `ForwardingNoticeSink` (Task 7).
- Produces:
  - `enum class VideoCompressionSupport { Supported, NeedsFfmpeg, Unsupported }`.
  - `MediaUploader.videoCompression: VideoCompressionSupport get() = Unsupported` (KDoc: whether `upload`/`compressIfNeeded` transcode `video/*` below UNCOMPRESSED; the composer hides the video controls unless `Supported` and shows the install hint for `NeedsFfmpeg`) and `suspend fun probeVideo(uri: MediaUri): VideoInfo? = null`.
  - `class DesktopMediaUploader(clientFor, httpClients: IRoleBasedHttpClientBuilder, private val notices: UserNoticeSink = UserNoticeSink {}, private val videoCompressor: VideoCompressor = FfmpegVideoCompressor())` — one ffmpeg dependency, no separate probe (a default `FfmpegProbe(FfmpegLocator.default.ffprobe)` parameter would resolve `ffprobe` at construction, possibly from composition). `httpClients` widens from `RoleBasedHttpClientBuilder` to the interface it implements (on the JVM `IRoleBasedHttpClientBuilder` is a typealias of `RoleBasedOkHttpClients`: seven `OkHttpClient`-returning functions plus `proxyPortForVideo(url): Int?`) so a test can stub it; the host passes `modules.roleBasedHttpClientBuilder` and `notices`.
  - `override val videoCompression get() = if (videoCompressor.available) Supported else NeedsFfmpeg`; `override suspend fun probeVideo(uri) = videoCompressor.probe(fileOf(uri))`.
  - `internal suspend fun <T> withVideoPrepared(progress: UploadOrchestrator, uri: MediaUri, mimeType: String?, quality: CompressorQuality, useH265: Boolean, stripMetadata: Boolean, convertGifToMp4: Boolean, progressCeiling: Double, maxBytes: Long? = null, block: suspend (file: File, prepared: Boolean) -> T): T?` — `mime = mimeType ?: mimeType(uri)`; `isVideo = mime starts with "video/"`, `isGif = mime == "image/gif"`. Decision, when `videoCompressor.available`:
    - `isGif && convertGifToMp4` → `convertGif`;
    - `isVideo && quality != UNCOMPRESSED` → `compress(source, quality, useH265, maxBytes)`;
    - `isVideo && quality == UNCOMPRESSED && stripMetadata` → `Original(strip(source))`;
    - otherwise → `block(fileOf(uri), false)`.
    Outcomes: `TooBig` → `null` (the caller reports `MEDIA_TOO_BIG_FOR_NIP95`); `Compressed(file)` → notices forwarded, `block(file, true)` with `file` deleted in `finally` under `NonCancellable`; `Original(stripped)` → notices forwarded, `block(stripped ?: fileOf(uri), stripped != null)` with `stripped` deleted likewise. Progress during the encode: `progress.updateState(0.02 + (progressCeiling - 0.02) * fraction, Compressing)`. Not available → `block(fileOf(uri), false)`.
  - Entry points: `upload`/`uploadEncrypted` wrap their Blossom call with `progressCeiling = 0.2`; `nip95` with `0.4` and `maxBytes = NIP95_MAX_BYTES`; `nip96` with `0.2`. Inside the block the pipeline receives `file`, `stripExif = stripMetadata && !prepared`, `quality = if (prepared) null else compressionQuality.toTarget()`. `nip95`/`nip96` gain `mimeType`, `useH265`, `convertGifToMp4` parameters forwarded from the callers; `preparePayload` takes the prepared `File` and a `prepared: Boolean` instead of the `MediaUri`.
  - `compressIfNeeded` override: same decision table but without the block; `Compressed(file)`/`Original(stripped != null)` → `MediaCompressorResult(StringMediaUri(file.absolutePath), "video/mp4", file.length())` (the caller's `discardTempFile` deletes it — it is under `AmethystTempDir`); `Original(null)`/not wanted → `MediaCompressorResult(uri, mimeType, null)`; `TooBig` cannot occur (no `maxBytes`).
  - `stripMetadata(uri, mimeType)` override: for `video/*` with ffmpeg available → `videoCompressor.strip(file)?.let { StringMediaUri(it.absolutePath) } ?: uri`; otherwise the existing JPEG path.

- [ ] **Step 1: Write the failing tests** with `FakeVideoCompressor(available, result: (File) -> VideoCompressionResult, onCompress: (File, CompressorQuality, Boolean) -> Unit, onGif: (File) -> Unit, progressEmits: List<Double>, stripResult: () -> File?, probeResult: VideoInfo? = VideoInfo(VideoResolution(1920, 1080), 30f), compressDelayMs: Long = 0)` (`compress` calls `onCompress`, `delay(compressDelayMs)`, emits each `progressEmits` value, returns `result(source)`; `convertGif` calls `onGif` then returns `result(source)`; `strip` returns `stripResult()`; `probe` returns `probeResult`), a `RecordingSink`, and `StubHttpClients` (an `object : IRoleBasedHttpClientBuilder` whose seven `OkHttpClient` functions return `OkHttpClient()`; `proxyPortForVideo` returns null). All tests `= runTest`; `src` and every `tempVideo(n)` live in a per-test directory, never in `AmethystTempDir`:

```kotlin
@Test fun supportMirrorsTheCompressor() { assertEquals(VideoCompressionSupport.Supported, uploader(available = true).videoCompression); assertEquals(VideoCompressionSupport.NeedsFfmpeg, uploader(available = false).videoCompression) }
@Test fun compressIfNeededReturnsMp4TempForVideo() = runTest {
    val out = tempVideo(10)
    val r = uploader(result = { VideoCompressionResult.Compressed(out) }).compressIfNeeded(UploadOrchestrator(), uri(src), "video/quicktime", CompressorQuality.HIGH, false, false)
    assertEquals(out.absolutePath, r.uri.toString()); assertEquals("video/mp4", r.contentType); assertEquals(10L, r.size)
}
@Test fun compressIfNeededReturnsStrippedOriginal() = runTest { val s = tempVideo(10); val r = uploader(result = { VideoCompressionResult.Original(s) }).compressIfNeeded(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, false); assertEquals(s.absolutePath, r.uri.toString()) }
@Test fun uncompressedAndUnavailablePassThrough() = runTest {
    assertEquals(src.absolutePath, uploader().compressIfNeeded(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.UNCOMPRESSED, false, false).uri.toString())
    assertEquals(src.absolutePath, uploader(available = false).compressIfNeeded(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, false).uri.toString())
}
@Test fun imagesNeverReachTheVideoCompressor() = runTest { var called = false; uploader(result = { called = true; VideoCompressionResult.Original(null) }).compressIfNeeded(UploadOrchestrator(), uri(src), "image/jpeg", CompressorQuality.HIGH, false, false); assertFalse(called) }
@Test fun gifIsConvertedOnlyWhenAsked() = runTest {
    var gifCalls = 0
    val u = uploader(result = { VideoCompressionResult.Original(null) }, onGif = { gifCalls++ })
    u.compressIfNeeded(UploadOrchestrator(), uri(src), "image/gif", CompressorQuality.UNCOMPRESSED, false, convertGifToMp4 = false); assertEquals(0, gifCalls)
    u.compressIfNeeded(UploadOrchestrator(), uri(src), "image/gif", CompressorQuality.UNCOMPRESSED, false, convertGifToMp4 = true); assertEquals(1, gifCalls)   // even at UNCOMPRESSED, as Android
}
@Test fun noticesAreForwarded() = runTest { val sink = RecordingSink(); uploader(result = { VideoCompressionResult.Original(null, listOf(UploadNotice.HdrSource)) }, sink = sink).compressIfNeeded(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, false); assertEquals(listOf(UploadNotice.HdrSource), sink.notices) }
@Test fun withVideoPreparedDeletesTempOnSuccess() = runTest {
    val out = tempVideo(10)
    assertEquals("ok", uploader(result = { VideoCompressionResult.Compressed(out) }).withVideoPrepared(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, true, false, 0.2) { f, prepared -> assertEquals(out, f); assertTrue(prepared); "ok" })
    assertFalse(out.exists()); assertTrue(src.exists())
}
@Test fun withVideoPreparedDeletesTempEvenWhenBlockThrows() = runTest {
    val out = tempVideo(10)
    assertFailsWith<IllegalStateException> { uploader(result = { VideoCompressionResult.Compressed(out) }).withVideoPrepared(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, true, false, 0.2) { _, _ -> error("upload failed") } }
    assertFalse(out.exists())
}
@Test fun withVideoPreparedDeletesTempWhenCancelledInsideTheBlock() = runTest {
    val out = tempVideo(10)
    val job = launch { uploader(result = { VideoCompressionResult.Compressed(out) }).withVideoPrepared(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, true, false, 0.2) { _, _ -> delay(10_000) } }
    advanceTimeBy(100); job.cancelAndJoin()
    assertFalse(out.exists())                                                       // deleted under NonCancellable
}
@Test fun cancellationDuringCompressionLeavesNothingToDelete() = runTest {
    var blockRan = false
    val job = launch { uploader(result = { VideoCompressionResult.Compressed(tempVideo(10)) }, compressDelayMs = 10_000).withVideoPrepared(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, true, false, 0.2) { _, _ -> blockRan = true } }
    advanceTimeBy(100); job.cancelAndJoin()
    assertFalse(blockRan); assertTrue(src.exists())
}
@Test fun withVideoPreparedReportsCompressingUpToTheCeiling() = runTest {
    val progress = UploadOrchestrator()
    uploader(result = { VideoCompressionResult.Compressed(tempVideo(10)) }, progressEmits = listOf(0.5)).withVideoPrepared(progress, uri(src), "video/mp4", CompressorQuality.HIGH, false, true, false, progressCeiling = 0.4) { _, prepared -> assertTrue(prepared) }
    assertEquals(0.21, progress.progress.value, 1e-9)                              // 0.02 + 0.38 * 0.5
    assertEquals(UploadingState.Compressing, progress.progressState.value)
}
@Test fun uncompressedVideoWithStripOnIsRemuxed() = runTest {
    val s = tempVideo(10)
    uploader(stripResult = { s }).withVideoPrepared(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.UNCOMPRESSED, false, stripMetadata = true, false, 0.2) { f, prepared -> assertEquals(s, f); assertTrue(prepared) }
}
@Test fun tooBigReturnsNull() = runTest { assertNull(uploader(result = { VideoCompressionResult.TooBig }).withVideoPrepared(UploadOrchestrator(), uri(src), "video/mp4", CompressorQuality.HIGH, false, true, false, 0.4, maxBytes = 80_000) { _, _ -> Unit }) }
@Test fun stripMetadataRemuxesVideo() = runTest { val s = tempVideo(10); assertEquals(s.absolutePath, uploader(stripResult = { s }).stripMetadata(uri(src), "video/mp4").toString()); assertEquals(uri(src), uploader(stripResult = { null }).stripMetadata(uri(src), "video/mp4")) }
@Test fun probeVideoReturnsInfo() = runTest { assertEquals(VideoResolution(1920, 1080), uploader().probeVideo(uri(src))!!.resolution) }
```

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement** the enum, the interface members, the Android override, `UnavailableMediaUploader`, the desktop uploader, the host wiring.
- [ ] **Step 4: Run** `./gradlew :desktopApp:test --tests "*DesktopMediaUploaderVideoTest" :amethyst:compilePlayDebugKotlin :commons:compileKotlinIosArm64` (the iOS task only if that target is configured on this machine; otherwise drop it) → PASS, compiles.
- [ ] **Step 5: Commit** — `feat(desktop): compress, strip and probe videos through ffmpeg in every upload path`

---

### Task 9: Slider steps and label become video-aware (`commons` + `commonsUI`)

**Files:**
- Modify: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/CompressorQuality.kt` (companion)
- Modify: `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/MultiOrchestrator.kt:54-60`
- Modify: `commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/note/creators/uploads/MediaQualitySlider.kt:80-133`
- Modify: `commonsUI/src/commonMain/composeResources/values/strings.xml:2125` (replace `media_compression_image_max_size`) and delete the same key from the three locales that translated it: `values-pl-rPL/strings.xml`, `values-hi-rIN/strings.xml`, `values-hu-rHU/strings.xml` (its value embeds the level name, so it cannot be composed with a video phrase; an orphaned translation would be reported by Crowdin)
- Test: `commons/src/jvmTest/kotlin/com/vitorpamplona/amethyst/commons/service/uploads/VideoAwareSliderStepsTest.kt`

**Interfaces:**
- Consumes: `hasVideoRule`, `videoLevel`, `VideoCompressionRules.ruleFor` (Task 1), `probeVideo` (Task 8).
- Produces, as pure functions in a new `object VideoAwareSliderSteps` (commonMain, same file as `CompressorQuality`), each taking the step list explicitly so the test can pass both platform lists:
  - `fun stepsFor(steps: List<CompressorQuality>, hasVideo: Boolean): List<CompressorQuality>` = `steps.filter { !hasVideo || it.hasVideoRule }`.
  - `fun snapForVideo(steps: List<CompressorQuality>, position: Int): Int` = `steps.indexOf(steps[position].videoLevel)`.
  - `fun toDisplayedIndex(steps: List<CompressorQuality>, position: Int, hasVideo: Boolean): Int` = index of `steps[if (hasVideo) snapForVideo(steps, position) else position]` in `stepsFor(steps, hasVideo)`.
  - `fun fromDisplayedIndex(steps: List<CompressorQuality>, index: Int, hasVideo: Boolean): Int` = `steps.indexOf(stepsFor(steps, hasVideo)[index])`.
  - `CompressorQuality.Companion` wrappers with the same names minus the `steps` parameter, bound to `platformSliderSteps`.
- `MultiOrchestrator.hasCompressibleImage(): Boolean` = any item with `isImage() == true && isCompressible()`; `fun firstVideo(): SelectedMedia?`.
- Strings: delete `media_compression_image_max_size` (base + the three locales); add `media_compression_images_up_to` = `images up to %1$d px`, `media_compression_video_target` = `%1$s video → %2$dp, %3$s Mbps` (e.g. `4K video → 2160p, 8 Mbps`; the units live in the resource so translators can move them), `media_compression_video_target_example` = `1080p video → %1$dp, %2$s Mbps` (used when the file could not be probed).
- `MediaQualitySlider`: `videoMode = media?.hasVideo() == true && uploader.videoCompression == VideoCompressionSupport.Supported` — **not** `hasVideo()` alone: on a platform that will not compress the video the slider governs only the images, so it must keep the 5-stop list and say nothing about video (otherwise a photo+video post on a desktop without ffmpeg would lose VERY_HIGH and promise a video target it cannot deliver). `steps = CompressorQuality.stepsFor(videoMode)`; `Slider(value = toDisplayedIndex(position, videoMode), valueRange 0..steps.lastIndex, steps = steps.size - 2, onValueChange = { onPositionChange(fromDisplayedIndex(it.toInt(), videoMode)) })`; `LaunchedEffect(videoMode) { if (videoMode) snapForVideo(position).let { if (it != position) onPositionChange(it) } }`. The video phrase: `val info by produceState<VideoInfo?>(null, media?.firstVideo()) { value = media?.firstVideo()?.let { uploader.probeVideo(it.uri) } }`; with `info` → `rule = ruleFor(quality, info.resolution.getStandard())` worded as `stringRes(Res.string.media_compression_video_target, standard.label, rule.shortSide, mbps(rule.bitrateMbps))` where `mbps()` drops a trailing `.0` (`2`, `0.75`, `8`); without → `media_compression_video_target_example` with the 1080p row's `shortSide` and bitrate. Label = `listOfNotNull(name, imagePart, videoPart).joinToString(" · ")`, `imagePart` only when `media?.hasCompressibleImage() == true && quality.imageMaxDimension != null`, `videoPart` only when `videoMode && quality != UNCOMPRESSED`.

- [ ] **Step 1: Write the failing tests**

```kotlin
private val DESKTOP = listOf(LOW, MEDIUM, HIGH, VERY_HIGH, UNCOMPRESSED)
private val PHONE = listOf(LOW, MEDIUM, HIGH, UNCOMPRESSED)
@Test fun videoStepsDropVeryHigh() { assertEquals(PHONE, VideoAwareSliderSteps.stepsFor(DESKTOP, true)); assertEquals(DESKTOP, VideoAwareSliderSteps.stepsFor(DESKTOP, false)); assertEquals(PHONE, VideoAwareSliderSteps.stepsFor(PHONE, true)) }
@Test fun veryHighSnapsToHigh() { assertEquals(2, VideoAwareSliderSteps.snapForVideo(DESKTOP, 3)); assertEquals(2, VideoAwareSliderSteps.snapForVideo(DESKTOP, 2)); assertEquals(4, VideoAwareSliderSteps.snapForVideo(DESKTOP, 4)); assertEquals(3, VideoAwareSliderSteps.snapForVideo(PHONE, 3)) }
@Test fun displayedIndexRoundTrips() {
    for (p in DESKTOP.indices) assertEquals(p, VideoAwareSliderSteps.fromDisplayedIndex(DESKTOP, VideoAwareSliderSteps.toDisplayedIndex(DESKTOP, p, false), false))
    assertEquals(3, VideoAwareSliderSteps.toDisplayedIndex(DESKTOP, 4, true)); assertEquals(4, VideoAwareSliderSteps.fromDisplayedIndex(DESKTOP, 3, true)); assertEquals(2, VideoAwareSliderSteps.toDisplayedIndex(DESKTOP, 3, true))
    for (p in PHONE.indices) assertEquals(p, VideoAwareSliderSteps.fromDisplayedIndex(PHONE, VideoAwareSliderSteps.toDisplayedIndex(PHONE, p, true), true))
}
@Test fun uncompressedStaysLast() { assertEquals(DESKTOP.lastIndex, VideoAwareSliderSteps.fromDisplayedIndex(DESKTOP, VideoAwareSliderSteps.stepsFor(DESKTOP, true).lastIndex, true)) }
```

- [ ] **Step 2: Run to verify they fail.** — [ ] **Step 3: Implement** the object and wrappers, `hasCompressibleImage`/`firstVideo`, the strings, the slider changes.
- [ ] **Step 4: Run** `./gradlew :commons:jvmTest --tests "*VideoAwareSliderStepsTest" :commonsUI:compileKotlinJvm` → PASS, compiles. Run `python3 .claude/hooks/compose_escaping_check.py` if present → no findings.
- [ ] **Step 5: Commit** — `feat(uploads): media-quality slider shows video stops and describes the picked video`

---

### Task 10: Dialog honesty — hide dead controls, fix the metadata toggle, "Upload Media"

**Files:**
- Modify: `commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/note/creators/uploads/ImageVideoDescription.kt:356-431`
- Modify: `commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/actions/NewMediaView.kt:225-277`
- Modify: `commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/screen/loggedIn/chats/utils/ChatFileUploadDialog.kt:238-270`
- Modify: `commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/actions/uploads/SelectFromGallery.kt:63,85,89-105` (`GallerySelectButton` gains a `label: StringResource` parameter; `SelectFromGallery` passes `upload_media`, `SelectSingleFromGallery` passes `upload_image`), `…/chats/privateDM/send/NewGroupDMScreen.kt:429`, `…/longs/NewLongVideoButton.kt:162`, `…/shorts/NewShortVideoButton.kt:176`, `…/video/NewVideoFeedButton.kt:208`
- Modify: `commonsUI/src/commonMain/composeResources/values/strings.xml` (after `upload_image`)

**Interfaces:**
- Consumes: `videoCompression` (Task 8), `hasCompressibleImage` (Task 9).
- Strings: `upload_media` = `Upload Media`; `video_compression_needs_ffmpeg` = `Install ffmpeg to compress videos. Until then videos are uploaded as they are.`
- Shared in each dialog: `val support = accountViewModel.host.mediaUploader.videoCompression`; `val canCompressVideo = support == VideoCompressionSupport.Supported`; `val hasVideo = …hasVideo() == true`; `val isVideoWithCompression = hasVideo && canCompressVideo && slider != uncompressedSliderPosition`; the hint `Text(stringRes(Res.string.video_compression_needs_ffmpeg), style = bodySmall, color = Color.Gray)` when `hasVideo && support == VideoCompressionSupport.NeedsFfmpeg`, placed where the H.265 switch would be (in the chat dialog: under the slider block).
- The three dialogs differ and keep their shapes; only conditions change:

  | Dialog | Slider block shown when | H.265 switch | GIF→MP4 switch | Strip-metadata toggle |
  | --- | --- | --- | --- | --- |
  | `ImageVideoDescription.kt:372-431` | `(hasCompressibleImage() \|\| (hasVideo && canCompressVideo)) && !convertGifToMp4` | `isVideoWithCompression` | `hasGif() && canCompressVideo` | hidden when `isVideoWithCompression` (today `:357` hides it on `hasVideo && slider != UNCOMPRESSED` — the bug) |
  | `NewMediaView.kt:225-277` | always (unchanged — it has no `hasCompressible` guard today) | `isVideoWithCompression` (today `hasVideo()`) | none — `NewMediaModel` has no `convertGifToMp4` state; do not add one | always (unchanged) |
  | `ChatFileUploadDialog.kt:238-270` | `hasCompressibleImage() \|\| (hasVideo && canCompressVideo)` (today `hasCompressible()`) | none — `ChatFileUploadState` has no `useH265`; do not add one | none | always (unchanged) |

- The five attach buttons: `Res.string.upload_media`. `SelectSingleFromGallery` (profile picture, banner, group and channel pictures), `NewPictureButton` and `ProfileHeader` keep `upload_image`.

- [ ] **Step 1: Apply the changes** (composition is covered by the manual test; the logic they consume is unit-tested in Tasks 8 and 9).
- [ ] **Step 2: Compile both front ends** — `./gradlew :commonsUI:compileKotlinJvm :amethyst:compilePlayDebugKotlin` → success.
- [ ] **Step 3: Run the desktop app** `./gradlew :desktopApp:run` with ffmpeg installed: picking a video shows 4 slider stops, a label naming the file's real resolution, the H.265 switch, and the metadata toggle hides below UNCOMPRESSED; photo + video together snaps VERY_HIGH → HIGH. Then `AMETHYST_FFMPEG_DISABLED=1 ./gradlew :desktopApp:run` (the `run` task's JVM inherits the environment; a bare `PATH` would not do, the locator finds Homebrew): the hint shows, no H.265/GIF switch, the metadata toggle stays, images still get the 5-stop slider and the photo+video label has no video phrase; the chat file dialog behaves the same. The post-composer attach tooltip reads "Upload Media"; the profile-picture picker still reads "Upload Image".
- [ ] **Step 4: Commit** — `fix(composer): hide video compression controls the platform cannot honour`

---

### Task 11: End-to-end verification and plan bookkeeping

**Files:**
- Modify: `desktopApp/plans/README.md` (add "phase 1 built" to the summary; keep "In progress" until merged)
- Create: `desktopApp/plans/2026-10-11-desktop-video-compression-manual-testing.md` (follow the format of `2026-08-20-live-media-manual-testing.md`)

- [ ] **Step 1: Full test run** — `./gradlew test` → BUILD SUCCESSFUL (with ffmpeg installed, so the gated tests run); then `AMETHYST_FFMPEG_DISABLED=1 ./gradlew :commons:jvmTest :desktopApp:test` → still green; `./gradlew :amethyst:compilePlayDebugKotlin`.
- [ ] **Step 2: The hash check** from the investigation: upload a **high-bitrate** 1080p clip (the manual sheet's `big.mp4`; the investigation's `file_example_MOV_1920_2_2MB.mov` is ~450 kbps, so every level above LOW encodes larger than it and the remuxed original goes up — it is the sheet's size-rule case, not the encoder case) from the desktop app at HIGH to blossom.band; `curl` the blob; `shasum -a 256` must differ from `ead8b50c…e40c62`; `ffprobe` must report 1920×1080, `h264`, video `bit_rate ≤ 4 400 000`, no `format_tags`. Repeat at LOW → 480p, and with H.265 → `hevc` (or the H.264 toast). Upload once at UNCOMPRESSED with strip on → hash differs from the source (remuxed), `ffprobe` shows the source's codec and no tags.
- [ ] **Step 3: Package and launch from Finder** — `./gradlew :desktopApp:packageDmg`, install, launch from Finder with Homebrew ffmpeg present → the video controls appear (Review Focus 5).
- [ ] **Step 4: Write the manual-testing sheet** covering: with ffmpeg and with `AMETHYST_FFMPEG_DISABLED=1`; the Finder launch; each stop; H.265 with and without an HEVC encoder; GIF→MP4; a portrait phone video; an HDR iPhone clip (toast shown, upload proceeds); three videos in one post (`pgrep ffmpeg` shows one at a time); quit mid-encode (`pgrep ffmpeg` empty afterwards, `AmethystTempDir.rootDir()` has no `amethyst_video_*`); a corrupt video (uploads original + toast); NIP-95 with a long clip refused before encoding; the chat file dialog with and without ffmpeg.
- [ ] **Step 5: Commit** — `docs(desktop): manual test sheet for desktop video compression`

Hand the branch and the sheet to the human; do not open a PR.