Skip to content

Debloat your Android TV, install apps, browse and transfer files on it, all from your phone. Just 3 MB, no tracking, no root, no PC.

Launch splash and a one-time welcome screen

jesse-agent-2323e7c8a554b58
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 470e52a..9b4c8dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ until this file has a section for its version.
## Unreleased
+- **New:** The app opens on its logo, then a one-time welcome for first-time users. [#PR](../../pull/PR)
- **Improved:** Overview puts the TV first, with chips to switch and debloat counts. [#64](../../pull/64)
- **Improved:** An offline TV keeps its maker and Android version after the app restarts. [#63](../../pull/63)
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
index ff0be09..3f554b4 100644
--- a/app/build.gradle.kts
+++ b/app/build.gradle.kts
@@ -124,6 +124,7 @@ dependencies {
implementation(project(":adb"))
implementation(libs.androidx.core.ktx)
+ implementation(libs.androidx.core.splashscreen)
implementation(libs.androidx.activity.compose)
implementation(libs.androidx.lifecycle.runtime.ktx)
implementation(libs.androidx.lifecycle.runtime.compose)
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
index 73f0a49..f4702a0 100644
--- a/app/src/main/AndroidManifest.xml
+++ b/app/src/main/AndroidManifest.xml
@@ -15,7 +15,7 @@
android:roundIcon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
- android:theme="@style/Theme.Tellyscope">
+ android:theme="@style/Theme.Tellyscope.Starting">
<activity
android:name=".MainActivity"
android:exported="true">
diff --git a/app/src/main/java/app/tellyscope/MainActivity.kt b/app/src/main/java/app/tellyscope/MainActivity.kt
index 0070f2a..ea3c6d5 100644
--- a/app/src/main/java/app/tellyscope/MainActivity.kt
+++ b/app/src/main/java/app/tellyscope/MainActivity.kt
@@ -28,6 +28,7 @@ import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.platform.LocalUriHandler
import androidx.core.content.ContextCompat
+import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleEventEffect
import androidx.lifecycle.compose.collectAsStateWithLifecycle
@@ -51,6 +52,7 @@ import app.tellyscope.ui.ScanScreen
import app.tellyscope.ui.SettingsScreen
import app.tellyscope.ui.TellyscopeViewModel
import app.tellyscope.ui.UpdateDialog
+import app.tellyscope.ui.WelcomeScreen
import app.tellyscope.ui.theme.TellyscopeTheme
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.filterNotNull
@@ -58,6 +60,7 @@ import java.io.File
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
+ installSplashScreen()
super.onCreate(savedInstanceState)
enableEdgeToEdge()
// Real TVs by default. Launch with `--es scenario fake|empty|noallow` to run on
@@ -68,21 +71,31 @@ class MainActivity : ComponentActivity() {
"noallow" -> FakeDeviceSource.Scenario.NoAllow
else -> null
}
+ // Existing installs with a saved TV never see the welcome; the marker keeps it to once.
+ val welcomed = File(filesDir, "welcomed")
+ val showWelcome = scenario == null && !welcomed.exists() && File(filesDir, "devices.tsv").length() == 0L
setContent {
TellyscopeTheme {
- LocalNetworkGate(skip = scenario != null) {
- val vm: TellyscopeViewModel = viewModel(
- factory = viewModelFactory {
- initializer {
- TellyscopeViewModel(
- scenario?.let(::FakeDeviceSource) ?: AdbDeviceSource(applicationContext),
- AndroidPhoneStorage(applicationContext),
- updates = if (scenario != null) null else updateCheck(),
- )
- }
- },
- )
- TellyscopeApp(vm)
+ var welcome by rememberSaveable { mutableStateOf(showWelcome) }
+ if (welcome) {
+ val done = { welcomed.createNewFile(); welcome = false }
+ WelcomeScreen(askLocalNetwork = Build.VERSION.SDK_INT >= 37, onContinue = done, onSkip = done)
+ } else {
+ // Straight from the welcome, Android's own dialog follows without a second screen in between.
+ LocalNetworkGate(skip = scenario != null, askNow = showWelcome) {
+ val vm: TellyscopeViewModel = viewModel(
+ factory = viewModelFactory {
+ initializer {
+ TellyscopeViewModel(
+ scenario?.let(::FakeDeviceSource) ?: AdbDeviceSource(applicationContext),
+ AndroidPhoneStorage(applicationContext),
+ updates = if (scenario != null) null else updateCheck(),
+ )
+ }
+ },
+ )
+ TellyscopeApp(vm)
+ }
}
}
}
@@ -101,7 +114,7 @@ class MainActivity : ComponentActivity() {
* [content], which keeps the first scan behind the grant.
*/
@Composable
- private fun LocalNetworkGate(skip: Boolean, content: @Composable () -> Unit) {
+ private fun LocalNetworkGate(skip: Boolean, askNow: Boolean, content: @Composable () -> Unit) {
// Not in Manifest.permission below API 37; the string is the same on every SDK.
val permission = "android.permission.ACCESS_LOCAL_NETWORK"
fun granted() = skip || Build.VERSION.SDK_INT < 37 ||
@@ -116,6 +129,7 @@ class MainActivity : ComponentActivity() {
// No rationale after a refusal means Android won't show its dialog again: only Settings can grant it.
canAsk = shouldShowRequestPermissionRationale(permission)
}
+ LaunchedEffect(Unit) { if (askNow && !ok && !denied) launcher.launch(permission) }
// Coming back from Settings.
LifecycleEventEffect(Lifecycle.Event.ON_RESUME) { ok = granted() }
diff --git a/app/src/main/java/app/tellyscope/ui/WelcomeScreen.kt b/app/src/main/java/app/tellyscope/ui/WelcomeScreen.kt
new file mode 100644
index 0000000..dfc4ec0
--- /dev/null
+++ b/app/src/main/java/app/tellyscope/ui/WelcomeScreen.kt
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: GPL-3.0-only
+
+package app.tellyscope.ui
+
+import androidx.compose.foundation.Image
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.requiredSize
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.Card
+import androidx.compose.material3.CardDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.res.colorResource
+import androidx.compose.ui.res.painterResource
+import androidx.compose.ui.unit.dp
+import app.tellyscope.R
+import app.tellyscope.ui.theme.SmallNumber
+
+/**
+ * Shown once, before the first scan. Skip and Continue both move on: Skip only passes over
+ * the reading. [askLocalNetwork] adds the line about the Android 17+ permission that follows.
+ */
+@Composable
+fun WelcomeScreen(askLocalNetwork: Boolean, onContinue: () -> Unit, onSkip: () -> Unit) {
+ Scaffold(
+ bottomBar = {
+ Row(
+ Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 16.dp),
+ horizontalArrangement = Arrangement.SpaceBetween,
+ verticalAlignment = Alignment.CenterVertically,
+ ) {
+ TextButton(onClick = onSkip) { Text("Skip") }
+ Button(onClick = onContinue) { Text("Continue") }
+ }
+ },
+ ) { pad ->
+ Column(
+ Modifier.fillMaxSize().padding(pad).verticalScroll(rememberScrollState()).padding(horizontal = 16.dp, vertical = 48.dp),
+ verticalArrangement = Arrangement.spacedBy(16.dp),
+ ) {
+ // The launcher icon's own teal in both themes, like the home screen and the splash.
+ Box(
+ Modifier.size(72.dp).clip(MaterialTheme.shapes.extraLarge).background(colorResource(R.color.splash_icon_background)),
+ contentAlignment = Alignment.Center,
+ ) {
+ // The foreground keeps its art inside the adaptive-icon safe zone; oversize it so the art fills the tile.
+ Image(painterResource(R.drawable.ic_launcher_foreground), contentDescription = null, Modifier.requiredSize(108.dp))
+ }
+ Text("Welcome to Tellyscope", style = MaterialTheme.typography.headlineMedium)
+ Text(
+ "See what's running on your Android TV, and turn off the apps you don't need. All from your phone, over Wi-Fi.",
+ style = MaterialTheme.typography.bodyLarge,
+ )
+ Card(
+ Modifier.fillMaxWidth(),
+ colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.surfaceContainerHigh),
+ ) {
+ Column(Modifier.padding(20.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
+ steps.forEachIndexed { i, step ->
+ Row {
+ Text("${i + 1}", Modifier.alignByBaseline(), style = SmallNumber, color = MaterialTheme.colorScheme.primary)
+ Spacer(Modifier.width(12.dp))
+ Text(step, Modifier.alignByBaseline(), style = MaterialTheme.typography.bodyLarge)
+ }
+ }
+ }
+ }
+ if (askLocalNetwork) {
+ Text(
+ "Android asks before an app talks to other devices on your Wi-Fi. Tellyscope only connects to the TVs you pick.",
+ style = MaterialTheme.typography.bodySmall,
+ color = MaterialTheme.colorScheme.onSurfaceVariant,
+ )
+ }
+ }
+ }
+}
+
+private val steps = listOf(
+ "Turn on debugging on your TV. The next screen shows how for your brand.",
+ "Tellyscope finds the TV on your Wi-Fi.",
+ "Type the code the TV shows, or choose Allow when it asks.",
+)
diff --git a/app/src/main/res/values-night/colors.xml b/app/src/main/res/values-night/colors.xml
new file mode 100644
index 0000000..1672a2b
--- /dev/null
+++ b/app/src/main/res/values-night/colors.xml
@@ -0,0 +1,4 @@
+<resources>
+ <color name="splash_background">#0E1415</color>
+ <color name="splash_icon_background">#00696B</color>
+</resources>
diff --git a/app/src/main/res/values/colors.xml b/app/src/main/res/values/colors.xml
new file mode 100644
index 0000000..820929e
--- /dev/null
+++ b/app/src/main/res/values/colors.xml
@@ -0,0 +1,5 @@
+<resources>
+ <!-- Match background and primary in ui/theme/Theme.kt. -->
+ <color name="splash_background">#F4FBFA</color>
+ <color name="splash_icon_background">#00696B</color>
+</resources>
diff --git a/app/src/main/res/values/themes.xml b/app/src/main/res/values/themes.xml
index 97f8e5e..8a5149c 100644
--- a/app/src/main/res/values/themes.xml
+++ b/app/src/main/res/values/themes.xml
@@ -1,4 +1,13 @@
<resources>
<!-- Window theme only; everything inside is Compose (see ui/theme/Theme.kt). -->
<style name="Theme.Tellyscope" parent="android:Theme.Material.Light.NoActionBar" />
+
+ <!-- Launch splash: the launcher logo on its teal disc, over the app's own background, so the
+ hand-off to the first screen has no colour jump. installSplashScreen() swaps in Theme.Tellyscope. -->
+ <style name="Theme.Tellyscope.Starting" parent="Theme.SplashScreen.IconBackground">
+ <item name="windowSplashScreenBackground">@color/splash_background</item>
+ <item name="windowSplashScreenAnimatedIcon">@drawable/ic_launcher_foreground</item>
+ <item name="windowSplashScreenIconBackgroundColor">@color/splash_icon_background</item>
+ <item name="postSplashScreenTheme">@style/Theme.Tellyscope</item>
+ </style>
</resources>
diff --git a/app/src/test/java/app/tellyscope/ScreenshotTest.kt b/app/src/test/java/app/tellyscope/ScreenshotTest.kt
index 2aad425..f3012ab 100644
--- a/app/src/test/java/app/tellyscope/ScreenshotTest.kt
+++ b/app/src/test/java/app/tellyscope/ScreenshotTest.kt
@@ -64,6 +64,7 @@ import app.tellyscope.ui.FilesBlock
import app.tellyscope.ui.FilesUi
import app.tellyscope.ui.RestoreDialog
import app.tellyscope.ui.PermissionScreen
+import app.tellyscope.ui.WelcomeScreen
import app.tellyscope.ui.RebootDialog
import app.tellyscope.ui.RemoteActions
import app.tellyscope.ui.RemoteScreen
@@ -574,6 +575,10 @@ class ScreenshotTest {
DeviceTabsScreen(deviceState { copy(transfer = t) }, DeviceActions())
}
+ @Test fun welcome() = shot("00_welcome") { WelcomeScreen(askLocalNetwork = true, {}, {}) }
+
+ @Test fun welcome_dark() = shot("00_welcome", dark = true) { WelcomeScreen(askLocalNetwork = true, {}, {}) }
+
@Test fun permission() = shot("08_permission") { PermissionScreen(denied = false, canAsk = true, {}, {}) }
@Test fun permission_denied() = shot("08_permission_denied") { PermissionScreen(denied = true, canAsk = true, {}, {}) }
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 6ae63f2..e3d5a10 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -6,6 +6,7 @@ compose-bom = "2026.09.00"
material3 = "1.5.0-beta02"
activity-compose = "1.13.0"
core-ktx = "1.19.1"
+core-splashscreen = "1.2.0"
lifecycle = "2.11.0"
kadb = "2.1.5"
# kadb-mdns stops at 2.1.4; 2.1.5 was not published for it.
@@ -18,6 +19,7 @@ junit = "4.13.2"
[libraries]
androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "core-ktx" }
+androidx-core-splashscreen = { module = "androidx.core:core-splashscreen", version.ref = "core-splashscreen" }
androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "activity-compose" }
androidx-lifecycle-runtime-ktx = { module = "androidx.lifecycle:lifecycle-runtime-ktx", version.ref = "lifecycle" }
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "compose-bom" }