memby/HOME_PERFORMANCE.md

Home performance baseline

This is the repeatable performance check for Home. The source baseline is the current good-performing release line at commit 5467fba (0.2.84). Numbers are only comparable on the same television, Android build, server, network and signed-in profile, so benchmark results belong with the test run or release notes rather than as universal targets here.

What is measured

• coldStartToHomeNoCompilation: cold launch without ahead-of-time compilation, used as the control for the baseline profile.
• coldStartToHomeWithProfile: cold launch as a release is shipped. timeToFullDisplayMs ends when Home reports its first D-pad-ready, settled frame.
• warmStartToHomeWithProfile: returning to a resident process.
• homeDpadAndRows: frame timing during rapid travel across cards, down four rows, and back through already displayed artwork. The route deliberately does not idle between presses.
• Debug milestones in MembyStartup: process start to home_visible, first_row_visible, and home_interactive.
• Debug frame windows in EmbyClientPerf: jank percentage, p50/p95/p99 UI frame time, frames over 16 ms and 33 ms, and the maximum frame time.

Compose Layout Inspector supplies card and row recomposition counts. Capture a system trace at the same time when a frame regression needs attribution; the trace shows Compose work, Coil fetch/decode activity and main-thread scheduling together.

Run protocol

Use a physical TV with a signed-in profile and a populated Home cache. Keep the TV's display mode, server, network and Home row preferences unchanged between the reference and candidate runs.

$env:JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
.\gradlew.bat :benchmark:connectedBenchmarkReleaseAndroidTest `
  -P android.testInstrumentationRunnerArguments.class=com.ponzischeme89.memby.benchmark.HomeBenchmark

For an interactive debug capture, clear logcat, cold-start Memby, wait for Home, then rapidly hold Right and move through at least four rows. Record:

adb logcat -s MembyStartup EmbyClientPerf

In Layout Inspector, enable recomposition counts and repeat the same route. Unchanged cards outside the old and new focus targets should normally be skipped; focus animation should not cause per-frame card recomposition. In Android Studio's system trace, inspect the slowest frames for main-thread Compose work and Coil image fetch/decode slices.

Regression gates

Use the median of at least five iterations. Investigate before release when, against a fresh reference run on the same setup:

• profiled cold-start timeToFullDisplayMs or warm start regresses by more than 10%;
• frameDurationCpuMs p95 regresses by more than 10%, or p99 crosses 33 ms;
• a previously displayed card causes a network fetch or another decode on the return pass;
• focus animation recomposes a card on every animation frame or invalidates unaffected cards;
• adding a Home row materially changes first-row visibility time. Below-the-fold rows may affect home_interactive, but must not delay first_row_visible.

Regenerate the baseline profile after changing the startup or first-browse path:

.\gradlew.bat :app:generateReleaseBaselineProfile

Keep the reference and candidate benchmark result directories together. Hardware variance makes the paired result the baseline; a number copied from a different TV is not evidence of a regression or an improvement.