Skip to content

Native Android client for Spotify, built with Jetpack Compose

Extensions: a user guide, linked from the Extensions page in both looks

kota-zo226f777b2831
diff --git a/README.md b/README.md
index bf731830..ba675fb1 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,7 @@ Obtainium (add `https://github.com/kota-zo/myspoti`; the stable app and the beta
- Installing shows what an extension will do (each action with its author's reason, the critical ones marked) and asks for one tick: you install it on your own responsibility. An extension gets every action it lists, or is not installed; an update that asks for more waits for your OK and shows only what changes.
- With an audio-source extension on, every song you play (from a list, search, an artist, Recents, a link or shuffle) is asked there first, and plays on Spotify when it has nothing.
- An extension can bring its own settings to Settings, Playback or Downloads (its quality, per network if it likes): the first source of the order shows its own, and an extension above Spotify replaces Spotify's quality settings there.
+- New to extensions? [The user guide](docs/extensions/GUIDE.md): the kinds, installing one, the order of the sources, and what to do when one does not work (Android Auto and Android TV too).
- For authors: [the extensions API](docs/extensions/API.md), and a desktop runner to test without a phone.
**And also**
diff --git a/base/app/src/main/java/com/music/spotui/ui/immersive/pages/ImmersiveExtensionsScreen.kt b/base/app/src/main/java/com/music/spotui/ui/immersive/pages/ImmersiveExtensionsScreen.kt
index a547d035..b3eabb7b 100644
--- a/base/app/src/main/java/com/music/spotui/ui/immersive/pages/ImmersiveExtensionsScreen.kt
+++ b/base/app/src/main/java/com/music/spotui/ui/immersive/pages/ImmersiveExtensionsScreen.kt
@@ -283,6 +283,7 @@ private fun EmptyState() {
Column(Modifier.fillMaxWidth()) {
Text(stringResource(R.string.extensions_empty_title), style = Immersive.BodyStrong)
Text(stringResource(R.string.extensions_empty_body), style = Immersive.Subhead, modifier = Modifier.padding(top = 4.dp))
+ com.music.spotui.ui.screens.GuideLink(Modifier.padding(top = 10.dp)) { Text(it, style = Immersive.BodyStrong, color = Immersive.Accent) }
}
}
diff --git a/base/app/src/main/java/com/music/spotui/ui/screens/ExtensionsScreen.kt b/base/app/src/main/java/com/music/spotui/ui/screens/ExtensionsScreen.kt
index 7790a994..3606b3b7 100644
--- a/base/app/src/main/java/com/music/spotui/ui/screens/ExtensionsScreen.kt
+++ b/base/app/src/main/java/com/music/spotui/ui/screens/ExtensionsScreen.kt
@@ -314,6 +314,7 @@ private fun EmptyState() {
Column(Modifier.fillMaxWidth().padding(horizontal = 20.dp, vertical = 8.dp)) {
Text(stringResource(R.string.extensions_empty_title), color = AppText, fontSize = 17.sp, fontWeight = FontWeight.Bold)
Text(stringResource(R.string.extensions_empty_body), color = AppMuted, fontSize = 13.sp, modifier = Modifier.padding(top = 4.dp))
+ GuideLink(Modifier.padding(top = 10.dp)) { Text(it, color = com.music.spotui.ui.theme.AppAccent, fontSize = 14.sp, fontWeight = FontWeight.Bold) }
}
}
@@ -537,3 +538,12 @@ private fun InstallButtons(onRepo: (() -> Unit)?, onFile: () -> Unit, onUrl: ()
OutlinedButton(onClick = onUrl, border = border) { Text(stringResource(R.string.extensions_install_url), color = AppText, fontSize = 13.sp) }
}
}
+
+/** The user guide to extensions (kinds, installing, troubleshooting), in the browser. */
+@Composable
+internal fun GuideLink(modifier: Modifier = Modifier, label: @Composable (String) -> Unit) {
+ val uriHandler = androidx.compose.ui.platform.LocalUriHandler.current
+ Box(modifier.clip(RoundedCornerShape(8.dp)).clickable { runCatching { uriHandler.openUri("https://github.com/kota-zo/myspoti/blob/main/docs/extensions/GUIDE.md") } }.padding(vertical = 6.dp)) {
+ label(stringResource(R.string.extensions_guide))
+ }
+}
diff --git a/base/app/src/main/res/values-de/extensions_strings.xml b/base/app/src/main/res/values-de/extensions_strings.xml
index 70423296..b7016220 100644
--- a/base/app/src/main/res/values-de/extensions_strings.xml
+++ b/base/app/src/main/res/values-de/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">In %1$d ms geöffnet</string>
<string name="why_source_skipped">übersprungen: %1$s</string>
<string name="why_source_title">Warum diese Quelle?</string>
+ <string name="extensions_guide">So installierst du Erweiterungen</string>
</resources>
diff --git a/base/app/src/main/res/values-el/extensions_strings.xml b/base/app/src/main/res/values-el/extensions_strings.xml
index 05e85d2d..76194720 100644
--- a/base/app/src/main/res/values-el/extensions_strings.xml
+++ b/base/app/src/main/res/values-el/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Άνοιξε σε %1$d ms</string>
<string name="why_source_skipped">παραλείφθηκε: %1$s</string>
<string name="why_source_title">Γιατί αυτή η πηγή;</string>
+ <string name="extensions_guide">Πώς να εγκαταστήσεις επεκτάσεις</string>
</resources>
diff --git a/base/app/src/main/res/values-es/extensions_strings.xml b/base/app/src/main/res/values-es/extensions_strings.xml
index 70377fbb..2480d212 100644
--- a/base/app/src/main/res/values-es/extensions_strings.xml
+++ b/base/app/src/main/res/values-es/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Abierta en %1$d ms</string>
<string name="why_source_skipped">omitida: %1$s</string>
<string name="why_source_title">¿Por qué esta fuente?</string>
+ <string name="extensions_guide">Cómo instalar extensiones</string>
</resources>
diff --git a/base/app/src/main/res/values-fr/extensions_strings.xml b/base/app/src/main/res/values-fr/extensions_strings.xml
index 9f013afd..1ac4a596 100644
--- a/base/app/src/main/res/values-fr/extensions_strings.xml
+++ b/base/app/src/main/res/values-fr/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="ext_setting_cell">%1$s · Données mobiles</string>
<string name="why_source_ext_quality">Son réglage : %1$s (%2$s)</string>
<string name="extensions_unreadable_file">Le fichier n\'a pas pu être lu</string>
+ <string name="extensions_guide">Comment installer des extensions</string>
</resources>
diff --git a/base/app/src/main/res/values-it/extensions_strings.xml b/base/app/src/main/res/values-it/extensions_strings.xml
index 705a08af..b2d31f1a 100644
--- a/base/app/src/main/res/values-it/extensions_strings.xml
+++ b/base/app/src/main/res/values-it/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Aperto in %1$d ms</string>
<string name="why_source_skipped">saltata: %1$s</string>
<string name="why_source_title">Perché questa sorgente?</string>
+ <string name="extensions_guide">Come installare le estensioni</string>
</resources>
diff --git a/base/app/src/main/res/values-pl/extensions_strings.xml b/base/app/src/main/res/values-pl/extensions_strings.xml
index c3792bcb..7a482489 100644
--- a/base/app/src/main/res/values-pl/extensions_strings.xml
+++ b/base/app/src/main/res/values-pl/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Otwarto w %1$d ms</string>
<string name="why_source_skipped">pominięte: %1$s</string>
<string name="why_source_title">Dlaczego to źródło?</string>
+ <string name="extensions_guide">Jak instalować rozszerzenia</string>
</resources>
diff --git a/base/app/src/main/res/values-pt-rBR/extensions_strings.xml b/base/app/src/main/res/values-pt-rBR/extensions_strings.xml
index 1fc17f4e..ff9acbf9 100644
--- a/base/app/src/main/res/values-pt-rBR/extensions_strings.xml
+++ b/base/app/src/main/res/values-pt-rBR/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Aberta em %1$d ms</string>
<string name="why_source_skipped">ignorada: %1$s</string>
<string name="why_source_title">Por que esta fonte?</string>
+ <string name="extensions_guide">Como instalar extensões</string>
</resources>
diff --git a/base/app/src/main/res/values-pt-rPT/extensions_strings.xml b/base/app/src/main/res/values-pt-rPT/extensions_strings.xml
index 091f218b..39c430ab 100644
--- a/base/app/src/main/res/values-pt-rPT/extensions_strings.xml
+++ b/base/app/src/main/res/values-pt-rPT/extensions_strings.xml
@@ -239,4 +239,5 @@
<string name="why_source_open_ok">Aberta em %1$d ms</string>
<string name="why_source_skipped">ignorada: %1$s</string>
<string name="why_source_title">Por que esta fonte?</string>
+ <string name="extensions_guide">Como instalar extensões</string>
</resources>
diff --git a/base/app/src/main/res/values-pt/extensions_strings.xml b/base/app/src/main/res/values-pt/extensions_strings.xml
index f11e3d8a..51e491ee 100644
--- a/base/app/src/main/res/values-pt/extensions_strings.xml
+++ b/base/app/src/main/res/values-pt/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Aberta em %1$d ms</string>
<string name="why_source_skipped">ignorada: %1$s</string>
<string name="why_source_title">Por que esta fonte?</string>
+ <string name="extensions_guide">Como instalar extensões</string>
</resources>
diff --git a/base/app/src/main/res/values-ru/extensions_strings.xml b/base/app/src/main/res/values-ru/extensions_strings.xml
index 29594cb6..36034827 100644
--- a/base/app/src/main/res/values-ru/extensions_strings.xml
+++ b/base/app/src/main/res/values-ru/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">Открыто за %1$d мс</string>
<string name="why_source_skipped">пропущено: %1$s</string>
<string name="why_source_title">Почему этот источник?</string>
+ <string name="extensions_guide">Как установить расширения</string>
</resources>
diff --git a/base/app/src/main/res/values-zh/extensions_strings.xml b/base/app/src/main/res/values-zh/extensions_strings.xml
index 729520f6..5648025d 100644
--- a/base/app/src/main/res/values-zh/extensions_strings.xml
+++ b/base/app/src/main/res/values-zh/extensions_strings.xml
@@ -243,4 +243,5 @@
<string name="why_source_open_ok">%1$d 毫秒内打开</string>
<string name="why_source_skipped">已跳过:%1$s</string>
<string name="why_source_title">为什么是这个来源?</string>
+ <string name="extensions_guide">如何安装扩展</string>
</resources>
diff --git a/base/app/src/main/res/values/extensions_strings.xml b/base/app/src/main/res/values/extensions_strings.xml
index 005165d0..d631c8a7 100644
--- a/base/app/src/main/res/values/extensions_strings.xml
+++ b/base/app/src/main/res/values/extensions_strings.xml
@@ -246,4 +246,5 @@
<string name="ext_setting_cell">%1$s · Mobile data</string>
<!-- "Why this source?": the chosen extension's own quality setting; %1$s is "Quality: FLAC", %2$s the extension. -->
<string name="why_source_ext_quality">Its setting: %1$s (%2$s)</string>
+ <string name="extensions_guide">How to install extensions</string>
</resources>
diff --git a/docs/extensions/GUIDE.md b/docs/extensions/GUIDE.md
new file mode 100644
index 00000000..94f964c1
--- /dev/null
+++ b/docs/extensions/GUIDE.md
@@ -0,0 +1,65 @@
+# Extensions: a guide for users
+
+Myspoti plays Spotify on its own. Extensions add what it does not do itself. Each one is a small
+script that runs in a sandbox and only does what it asked for when you installed it.
+
+For extension authors, see [API.md](API.md).
+
+## What kinds there are
+
+| Kind | What it does | Where you see it |
+|---|---|---|
+| **Audio source** | Gives the audio of the songs you play, from a source of its own (its quality, often lossless). A song it has no audio for plays from Spotify, as before. | Settings, Playback: the source order and the extension's quality |
+| **Download source** | Lets you download songs, albums, playlists and Liked Songs to play with no connection. Myspoti keeps the files encrypted on your phone. | The download button on songs and lists; Settings, Downloads |
+| **Lyrics** | Lyrics from other catalogues when Spotify has none, or word by word. | The lyrics screen |
+| **Other** | Home or search shelves, player buttons, tools that use your Spotify account. | Where the extension says, after you install it |
+
+Myspoti ships no audio or download source of its own: what an extension plays or downloads comes
+from where its author says, under that author's responsibility.
+
+## Installing one
+
+1. Open **Settings, Extensions**.
+2. Either:
+ - **From a repository**: on the **Store** tab, add the repository address the extension's
+ author gives you (it ends in `index.json`), then pick the extension in the list. A repository
+ keeps its extensions up to date.
+ - **From a package**: install the `.zip` file you were given, or paste its address.
+3. Read what the extension will do. Every action it asks for is listed with its author's reason,
+ and the critical ones are marked. You install it on your own responsibility, and only install
+ from people you trust.
+4. Some extensions need a sign-in or a setting of their own: their page opens after the install.
+
+An update that asks for more than before waits for your OK and shows only what changes.
+
+## The order of the sources
+
+With several audio sources, Settings, Playback lists them in order: a song is asked to the first,
+then the next, and plays from Spotify when none has it. A newly installed extension goes first.
+Drag to change the order, or switch one off without removing it.
+
+## When something does not work
+
+| You see | What it usually means | What to try |
+|---|---|---|
+| The extension says the song is not available or "not reachable from the source", or the song plays from Spotify | The extension's source has no copy of that song (or matched none) | Nothing is wrong in Myspoti: the song plays from Spotify. Another source may have it. |
+| "Not answering for now", a source named on a failed download | The extension's server is down, slow or limits you | Try again later; the app sets a source aside for a while after repeated timeouts. |
+| An extension that cannot sign in or connect | Often a VPN, a DNS blocker or an expired session | Turn the VPN off for the sign-in, then sign in again from the extension's page. |
+| "No matching recording found" on downloads | The download source found no file of the right length for that song | Try another quality, or another download source. |
+| Downloads stop when the app is closed | The phone's battery saver stops the app | Settings, Battery: let Myspoti run in the background. |
+
+Report a problem to the extension's author first: Myspoti cannot change what a source answers.
+For Myspoti itself, **Export a diagnostic report** in Settings writes one with personal details
+masked, to attach to your report.
+
+## Android Auto
+
+Android Auto lists only apps installed from the Play Store, unless you allow others: in the
+Android Auto settings on the phone, tap **Version** about ten times to unlock the developer
+settings, then turn on **Unknown sources**. Myspoti then shows in the car's app list.
+
+## Android TV
+
+On a TV, Myspoti opens a short version for the remote: your Library, Liked Songs, Search and the
+player. Install the `armeabi-v7a` APK on most TV boxes (the `arm64-v8a` one on recent ones), and
+sign in once with the remote. Extensions, downloads and settings stay on the phone version.