Voor wie is dit codeboek?
Voor iemand die Kotlin een beetje kent, of die gewoon wil snappen hoe een
echte Android-app werkt. Je moet weten wat een bestand en een map zijn.
Woorden als ViewModel, repository en service worden
uitgelegd voordat ze belangrijk worden.
Zo lees je dit boek
-
Lees eerst het verhaal. Hoofdstuk 2 legt uit welke onderdelen
er zijn en hoe ze samenwerken. Je hoeft nog niets uit je hoofd te leren.
-
Volg één actie. Kies bijvoorbeeld “een boek openen” en volg
die route door de bestanden. Dat werkt beter dan alle bestanden op alfabet
lezen.
-
Kijk naar de codefragmenten. Ze zijn kort en komen uit de
echte code. De bestandsnaam staat erboven, zodat je verder kunt zoeken.
-
Gebruik de woordenlijst. Kom je een begrip tegen dat je nog
niet kent? Hoofdstuk 16 legt het kort uit.
Wat is DaisySpeler?
DaisySpeler is een Android-app waarmee je luisterboeken in het
DAISY 2.02-formaat kunt openen en beluisteren. Je kunt een
uitgepakte boekmap kiezen, een ZIP-bestand importeren of een boek downloaden
via de ingebouwde boekbrowser. De app onthoudt waar je gebleven bent, maakt
bookmarks en kan op de achtergrond doorspelen.
Wat de app wél doet
- DAISY 2.02 lezen:
ncc.html, optioneel book.opf en SMIL-bestanden.
- Losse audioclips aan elkaar plakken tot één doorlopende tijdlijn.
- Hoofdstukken, pagina's, bookmarks en een slaaptimer tonen.
- Op de achtergrond afspelen via een media-sessie en melding.
Wat de app níet doet
- Geen DAISY 3 of andere luisterboekformaten.
- Geen gesynchroniseerde tekstweergave tijdens het luisteren.
- Geen brede toegang tot al je bestanden: de app werkt met wat jij kiest.
- Geen account bij DaisySpeler zelf: luistergegevens blijven lokaal.
De drie getallen om te onthouden
6.0
app-versie
59
Kotlin-bestanden in de app
±9.500
regels code in app/src/main/java
De aantallen komen uit de mainbranch op het moment van schrijven. Ze veranderen
zodra iemand code toevoegt of verwijdert.
▤
De balie
De schermen. Hier tik je op knoppen en zie je de boeken. De UI bezit geen audio en leest geen bestanden.
☷
De receptionist
De ViewModels. Ze vertalen een tik naar een opdracht en houden bij wat het scherm moet tonen.
▦
Het magazijn
Repositories en parsers. Ze vinden, lezen, controleren en bewaren boeken, bookmarks en instellingen.
◉
De studio
De playback-service. Die bezit de echte speler en blijft doorspelen als het scherm weg is.
De lagen onder elkaar
UI
Compose-schermen: bibliotheek, speler, browser, over-scherm
ViewModels
State, gebruikersacties en verbinding met de speler
Data
Repositories, parsers, import, download en opslag
Opslag
JSON-bestanden, app-mappen, SAF-map of ZIP-uitpakmap
De playback-service staat een beetje apart. Hij hoort niet bij
één scherm: hij kan blijven draaien terwijl de app op de achtergrond staat. De
UI praat met die service via een MediaController. Dat is een soort
afstandsbediening met een vaste set opdrachten.
Wat is DAISY eigenlijk?
DAISY in één alinea
DAISY staat voor Digital Accessible Information System: een standaard
voor toegankelijke luisterboeken. Een DAISY 2.02-boek is niet één groot
audiobestand, maar een map met een inhoudsopgave
(ncc.html), kleine navigatie- en audioaanwijzingen
(.smil) en één of meer audiobestanden. DaisySpeler leest die
aanwijzingen en bouwt daar één doorlopende luisterervaring van.
Wat zit er in een boekmap?
| Bestand | Wat het is | Wat de app ermee doet |
ncc.html | Inhoudsopgave en informatie over het boek. | Titel, auteur, taal, navigatiepunten en omslag lezen. |
book.opf | Optionele pakketbeschrijving. | Extra metadata, volgorde van SMIL-bestanden en omslaginformatie lezen. |
*.smil | Koppeling tussen een stuk tekst en een stuk audio. | Per <par> lezen welke audio wanneer start en stopt. |
*.mp3, *.wav | De echte audio. | Als playlist aan ExoPlayer geven, met begin- en eindpunt per segment. |
| Afbeeldingen | Omslag of illustraties. | Omslag opsporen en lokaal bewaren. |
De reis van één boek
-
1
Kiezen
De gebruiker tikt op een boek in de bibliotheek.
-
2
Laden
De repository leest het boek en de parser maakt een
DaisyBook.
-
3
Klaarzetten
De service bouwt media-items en zet de speler op de opgeslagen positie.
-
4
Spelen
ExoPlayer speelt de segmenten als één doorlopende lijst af.
-
5
Onthouden
Positie en bookmarks worden lokaal opgeslagen.
DaisySpeler/
├── app/
│ └── src/
│ ├── main/
│ │ ├── AndroidManifest.xml app aanmelden bij Android
│ │ ├── java/nl/simon/daisyspeler/
│ │ │ ├── DaisyApplication.kt startpunt van de app
│ │ │ ├── AppContainer.kt alle vaste onderdelen aanmaken
│ │ │ ├── MainActivity.kt het eerste scherm starten
│ │ │ ├── Navigation.kt schermen aan elkaar knopen
│ │ │ ├── data/ boeken, opslag, import
│ │ │ ├── playback/ de muziekmotor
│ │ │ ├── ui/ schermen en vormgeving
│ │ │ └── util/ datum- en tijdformattering
│ │ └── res/ app-naam, thema, iconen
│ ├── test/ snelle unit tests
│ └── androidTest/ tests op een toestel/emulator
├── docs/
│ ├── regression-tests.md testafspraken
│ └── codeboek/ dit codeboek
├── gradle/libs.versions.toml versies van bibliotheken
└── README.md gebruikershandleiding
De belangrijkste pakketten
| Map | Rol | Beginnerstip |
data/book/ |
De dataclasses die een boek voorstellen. |
Begin bij Models.kt; daar leer je de woordenschat van de app. |
data/parser/ |
NCC, OPF en SMIL lezen en omzetten naar één tijdlijn. |
Lees DaisyBookLoader.kt van boven naar beneden. |
data/storage/ |
Bibliotheek, bookmarks, slaaptimer en voorkeuren bewaren. |
Kijk eerst naar de kleine JsonFileStore.kt. |
data/importer/ |
ZIP-bestanden veilig uitpakken. |
Lees de beveiligingschecks in ZipBookExtractor.kt. |
data/download/ |
Boekbrowser-downloads en automatische import. |
Volg één download van enqueue tot importCompleted. |
data/source/ |
Eén interface voor een SAF-map en een uitgepakte ZIP-map. |
Dit is een mooi voorbeeld van een abstractie. |
playback/ |
ExoPlayer, MediaSession, bookmarks en slaaptimer aansturen. |
Het grootste bestand; lees het in hoofdstuk 9 met een route. |
ui/ |
Compose-schermen, ViewModels en thema. |
Kies één scherm en volg de knop die je interesseert. |
De bouwstenen
De belangrijkste technische keuzes staan in app/build.gradle.kts en
gradle/libs.versions.toml. Je hoeft ze niet uit je hoofd te kennen,
maar het helpt om te weten waarom een bestand bepaalde imports heeft.
| Onderdeel | Keuze in dit project | Waarvoor |
| Taal | Kotlin 2.3.20 | De hele app, inclusief de UI. |
| UI | Jetpack Compose + Material 3 | Schermen als Kotlin-functies, zonder XML-layouts. |
| Navigatie | Navigation 3 | Routes en de terug-stack tussen schermen. |
| Audio | Media3 / ExoPlayer | Afspelen, mediasessies, meldingen en achtergrondbediening. |
| HTML en XML | jsoup + W3C DOM | NCC lezen met jsoup; OPF en SMIL met de DOM-parser. |
| JSON | kotlinx.serialization | Bibliotheek, bookmarks en slaaptimer bewaren. |
| Android-versies | minSdk 24, target/compile 36 | Draait op Android 7.0 en nieuwer. |
| Build | Gradle + JDK 17 | Compileren, testen en een APK maken. |
Zelf bouwen
Met JDK 17 en Android SDK 36 bouw je de app met
./gradlew :app:testDebugUnitTest :app:assembleDebug. De APK komt
daarna in app/build/outputs/apk/debug/app-debug.apk.
Tip: zoek op gedrag, niet op bestandsnaam
Weet je niet waar iets gebeurt? Zoek in je editor op een stukje tekst dat je
in de app ziet, bijvoorbeeld Verder luisteren of
SLEEP_TIMER. Vaak kom je sneller bij de juiste code dan door
willekeurig mappen te openen.
Stap 1: de Application
DaisyApplication is het eerste object dat Android voor de app
aanmaakt. Hier wordt AppContainer gebouwd. Die container leeft
zolang het app-proces leeft.
app/src/main/java/nl/simon/daisyspeler/DaisyApplication.kt
class DaisyApplication : Application() {
lateinit var container: AppContainer
private set
override fun onCreate() {
super.onCreate()
container = AppContainer(this)
}
}
Stap 2: de container
AppContainer is geen Android-onderdeel, maar een gewoon Kotlin-object.
Het maakt de repositories, de importer, de downloader en de slaaptimer één keer
aan. Elk scherm krijgt dezelfde container mee. Zo weet iedereen bij dezelfde
bibliotheek en dezelfde instellingen.
app/src/main/java/nl/simon/daisyspeler/AppContainer.kt (ingekort)
val libraryRepository = LibraryRepository(File(filesDir, "library.json"))
val bookmarkRepository = BookmarkRepository(File(filesDir, "bookmarks.json"))
val sleepTimerManager = SleepTimerManager(File(filesDir, "sleep_timer.json"))
val uiPreferences = UiPreferences(context)
val bookRepository = BookRepository(context, libraryRepository)
val bookImporter = BookImporter(bookRepository, libraryRepository)
val audiobookDownloads = AudiobookDownloads(context, uiPreferences)
In dezelfde container wordt ook een BroadcastReceiver aangemeld.
Die luistert naar het systeem als een download klaar is. Zo kan een boek
automatisch in de bibliotheek belanden, ook als de boekbrowser al dicht is.
Stap 3: de Activity
MainActivity zet de Compose-interface klaar. Op Android 13 en
nieuwer vraagt de app één keer om meldingen te mogen tonen. Daarna start
MainNavigation.
app/src/main/java/nl/simon/daisyspeler/MainActivity.kt (ingekort)
val container = (application as DaisyApplication).container
setContent {
DaisySpelerTheme {
MainNavigation(
container = container,
onExit = { finishAndRemoveTask() },
)
}
}
Stap 4: navigatie
De app gebruikt Navigation 3. Elke bestemming is een klein, serialiseerbaar
object. De backstack bepaalt welk scherm je ziet. Als je vanuit de speler
teruggaat, vraagt de navigatie eerst aan de playback-service om het boek netjes
te stoppen.
| Route | Scherm | Bijzonderheid |
LibraryRoute | Bibliotheek | Startpunt van de app. |
PlayerRoute(bookId) | Speler | Weet welk boek geopend moet worden. |
CoverBrowserRoute(bookId) | Omslag zoeken | Opent Google Afbeeldingen voor één boek. |
BookBrowserRoute(site) | Boekbrowser | Opent één van de twee ondersteunde boekwebsites. |
AboutRoute | Over DaisySpeler | Versie, help en licentie. |
Waarom een container in plaats van een framework?
De app is klein genoeg om dependencies met de hand te maken. Dat is
beginnersvriendelijk: je kunt in één bestand zien welke onderdelen bestaan.
Bij een grotere app zou je waarschijnlijk een dependency-injection-framework
gebruiken.
Let op: de container is geen wondermiddel
Een repository die in de container zit, blijft bestaan zolang het proces
leeft. Grote objecten zoals een volledig geparsed boek worden daarom apart
gecachet en weer vergeten als de speler het boek loslaat.
Eén boek in de lijst
Een LibraryEntry is de administratie van een boek. Niet de audio
zelf, maar de gegevens die de boekenplank nodig heeft.
app/src/main/java/nl/simon/daisyspeler/data/storage/StorageModels.kt
@Serializable
data class LibraryEntry(
val id: String,
val treeUri: String,
val title: String,
val author: String?,
val durationMs: Long,
val tocCount: Int,
val addedAtEpochMs: Long,
val lastPosition: BookPosition? = null,
val lastReadAtEpochMs: Long? = null,
val sourceType: LibrarySourceType = LibrarySourceType.FOLDER,
val localDir: String? = null,
val coverPath: String? = null,
)
| Veld | Betekenis voor een beginner |
id | Een korte code die dit boek uniek maakt. |
treeUri | De verwijzing naar de gekozen map of het ZIP-bestand. |
title, author | Wat op de boekenplank staat. |
durationMs | Totale luisterduur in milliseconden. |
lastPosition | Waar je gebleven bent: bronbestand, offset en globale tijd. |
lastReadAtEpochMs | Wanneer je het boek voor het laatst opende; gebruikt voor sorteren. |
sourceType | Map of ZIP. Bepaalt hoe de app het boek later terugvindt. |
localDir | Bij een ZIP: de uitgepakte map in app-eigen opslag. |
coverPath | Pad naar de lokale omslagafbeelding. |
De route door de code
LibraryScreen.kt toont de boeken en de knoppen.
LibraryViewModel.kt combineert de boekenlijst met de gekozen sortering.
LibraryRepository.kt bewaart elke wijziging in library.json.
JsonFileStore.kt schrijft eerst naar een tijdelijk bestand en hernoemt dat daarna.
Wat is een StateFlow?
Een StateFlow is een houder met een actuele waarde. Als de
waarde verandert, krijgen schermen die meelezen automatisch een update.
Daardoor hoeft de UI niet steeds zelf te vragen: “is er nog iets veranderd?”
Sorteren
De boekenplank kan alfabetisch of op “laatst gelezen” sorteren. Alfabetisch
gebruikt een Nederlandse collator, zodat bijvoorbeeld “ij” en “y” netjes
worden vergeleken. Bij “laatst gelezen” komen boeken die je al eens opende
eerst; daarna telt wanneer ze zijn toegevoegd.
De sorteervolgorde verandert niets aan de opgeslagen lijst. Alleen de weergave
wordt gesorteerd. De keuze zelf wordt in SharedPreferences bewaard.
Een boek verwijderen
Verwijderen is meer dan één regel uit de lijst halen. De app:
- stopt het boek in de playback-service als het daar openstaat;
- verwijdert de bookmarks van dat boek;
- gooit de geparseerde versie uit het geheugen;
- verwijdert bij een ZIP-import de uitgepakte bestanden en de omslag;
- geeft bij een mapimport de tijdelijke leestoestemming weer vrij.
Het originele ZIP-bestand en een gekozen map blijven altijd staan. De app
ruimt alleen haar eigen kopieën op.
Opnieuw importeren
Importeer je dezelfde map opnieuw, dan leest de app de actuele inhoud. De knop
“Verder luisteren” en een bestaande omslag blijven bewaard. Dat gebeurt in
LibraryRepository.addOrUpdate: oude velden worden alleen
overgenomen als de nieuwe import ze niet meebrengt.
Deur 1
Een map kiezen
Via de Android-mapkiezer (Storage Access Framework) kiest de gebruiker de
uitgepakte DAISY-map. De app vraagt om blijvende leestoegang, zodat het boek
later opnieuw geopend kan worden.
Wordt de map verplaatst of verwijderd, dan kan de app het boek niet meer
openen. De app maakt geen kopie van een mapimport.
Deur 2
Een ZIP-bestand kiezen
De app pakt het ZIP-bestand uit naar haar eigen opslag, leest het boek en
bewaart de uitgepakte map. Daarna speelt het boek net als een mapimport.
Het originele ZIP-bestand blijft staan. Bij verwijderen uit de bibliotheek
ruimt de app alleen de uitgepakte kopie op.
Dezelfde ingang voor beide deuren
BookImporter is expres klein. Het kiest de juiste importmethode en
zet daarna de boekgegevens in de bibliotheek. De boekbrowser gebruikt dezelfde
importeur, zodat een handmatige import en een download zich hetzelfde gedragen.
app/src/main/java/nl/simon/daisyspeler/data/BookImporter.kt (ingekort)
val loaded =
if (isZip) bookRepository.importZip(uri)
else bookRepository.importTree(uri.toString())
libraryRepository.addOrUpdate(
LibraryEntry(
id = loaded.id,
treeUri = uri.toString(),
title = book.title.ifBlank { "Naamloos boek" },
author = book.author,
durationMs = book.totalDurationMs,
sourceType = if (isZip) LibrarySourceType.ZIP else LibrarySourceType.FOLDER,
localDir = loaded.localDir,
coverPath = loaded.coverPath,
)
)
Een ZIP uitpakken is beveiligingswerk
Een ZIP-bestand komt van buiten de app. De inhoud kan kwaadwillende paden
bevatten, zoals ../../belangrijk-bestand. ZipBookExtractor
controleert daarom elk pad voordat er iets wordt geschreven.
app/src/main/java/nl/simon/daisyspeler/data/importer/ZipBookExtractor.kt
val parts = name.split('/').filter { it.isNotEmpty() && it != "." }
if (parts.isEmpty()) return null
if (parts.any { it == ".." }) {
throw ZipImportException("Het ZIP-bestand bevat een onveilig bestandspad.")
}
Verder gelden deze grenzen:
- Geen absolute paden en geen
.. in de bestandsnaam.
- Verborgen bestanden en de map
__MACOSX worden overgeslagen.
- Maximaal 50.000 bestanden en 8 GiB uitgepakte data.
- De app controleert of er genoeg vrije ruimte is.
- Bij een fout wordt de tijdelijke map opgeruimd en waar mogelijk de oude versie teruggezet.
Veilig vervangen
Bij een nieuwe import van hetzelfde ZIP-bestand gebruikt de app drie mappen:
id.tmp voor het uitpakken, id voor de actieve versie en
id.backup voor de oude versie. Eerst wordt alles uitgepakt en
geparsed. Pas als dat lukt, wordt de oude map opzijgeschoven en de nieuwe
actief. Gaat er iets mis, dan kan de oude map terugkomen.
Waarom een tijdelijke map?
Stel je voor dat je een boek aan het vervangen bent en de app wordt halverwege
afgesloten. Zonder tijdelijke map zou je een half uitgepakt boek houden. Met
de temporary-map blijft de oude, werkende versie staan tot de nieuwe klaar is.
Dezelfde code voor map en ZIP
De parser wil niet weten of een boek in een SAF-map of in app-opslag staat. Beide
gevallen implementeren dezelfde kleine interface:
app/src/main/java/nl/simon/daisyspeler/data/source/BookSource.kt
interface BookSource {
fun files(): List<SourceFile>
fun open(path: String): InputStream
/** Returns a URI string that ExoPlayer can open. */
fun playableUri(path: String): String
}
SafBookSource gebruikt de Android-contentresolver en
FileBookSource gebruikt gewone bestanden. De parser en de speler
werken met allebei via dezelfde drie functies. Dat is het nut van een abstractie:
één afspraak, meerdere uitvoeringen.
Waarom een boek-ID een hash is
Een map-URI kan lang en bijzonder zijn. De app maakt daar met SHA-256 een korte,
stabiele code van. Voor een ZIP wordt zip: vóór de URI gezet, zodat
een map en een ZIP nooit dezelfde ID krijgen.
Importeren en tegelijk een ander boek openen
De repository gebruikt een lock per boek en een aparte
importpoort. Een grote import van boek A hoeft het openen van boek B
daardoor niet tegen te houden. Imports onderling worden wel na elkaar gedaan,
zodat twee ZIP-bestanden niet tegelijk dezelfde mappen proberen te vervangen.
Een fout is geen ramp
Als een nieuwe import mislukt, probeert de app de vorige versie te herstellen.
Lukt ook dat niet, dan blijft de fout zichtbaar in de bibliotheek. De app
probeert nooit stilletjes een half boek te openen.
Eerst de vorm van een SMIL-bestand
Een SMIL-bestand zegt: “dit stuk tekst hoort bij dit stuk audio”. Hieronder staat
een vereenvoudigd voorbeeld. De echte bestanden kunnen meer elementen bevatten.
Vereenvoudigd DAISY 2.02 SMIL-fragment
<smil>
<body>
<par>
<text src="page.html#p1" />
<audio src="audio/part01.mp3"
clip-begin="npt=0.000s"
clip-end="npt=12.345s" />
</par>
</body>
</smil>
Eén <par> koppelt een tekstfragment aan één audioclip. Een boek
heeft er vaak honderden of duizenden. DaisySpeler leest ze allemaal en plakt
naburige clips aan elkaar.
Wat betekent npt=?
npt staat voor normal play time: een tijd binnen het
audiobestand. npt=12.345s betekent 12,345 seconde;
npt=01:02.345 betekent 1 minuut en 2,345 seconde.
TimeParser zet die notatie om naar milliseconden.
De parser in acht stappen
-
Bestanden inventariseren. De loader maakt een lijst van alle
bestanden en een index waarbij hoofdletters geen verschil maken.
-
ncc.html vinden. De app kiest de ondiepst
gelegen NCC. Zonder NCC stopt de import met een duidelijke fout.
-
NCC lezen. Titel, auteur, taal, totale tijd, navigatiepunten
en een eventuele omslag komen binnen via
NccParser.
-
OPF lezen, als die er is.
OpfParser levert extra
metadata, de volgorde van SMIL-bestanden en soms een betere omslag.
-
SMIL-bestanden ordenen. Eerst de OPF-spine, dan de NCC-volgorde,
dan een eventueel
er_book_info.xml en ten slotte de rest.
-
Cliplijst maken. Elk audioclip wordt aan een echt bestand
gekoppeld. Ontbreekt een eindtijd, dan zoekt de parser de start van een latere
clip in hetzelfde audiobestand.
-
Segmenten bouwen. Aangrenzende clips uit hetzelfde bestand
worden samengevoegd. Elk segment krijgt een plek op de globale tijdlijn.
-
Navigatie koppelen. Elk NCC-punt wordt aan een segment en een
offset gekoppeld. Lukt dat niet, dan maakt de app een eenvoudige indeling per
audiobestand.
Het resultaat: DaisyBook
app/src/main/java/nl/simon/daisyspeler/data/book/Models.kt (ingekort)
data class DaisyBook(
val title: String,
val author: String?,
val language: String?,
val totalDurationMs: Long,
val segments: List<AudioSegment>,
val toc: List<NavPoint>,
val warnings: List<String> = emptyList(),
val coverPath: String? = null,
)
De inhoudsopgave is een lijst NavPoint-objecten. Elk punt heeft een
type, zodat de app koppen en pagina's anders kan tonen:
| Type | Betekenis |
HEADING | Een hoofdstuk of kop. |
PAGE | Een paginanummer uit het boek. |
SIDEBAR | Een zijbalk of extra tekstblok. |
FOOTNOTE | Een voetnoot. |
PRODNOTE | Een producentnotitie, bijvoorbeeld over de opname. |
OTHER | Overige navigatie, zoals een aantekening. |
Een AudioSegment is één stuk audio uit één bestand. Het heeft twee
soorten tijden: waar het stuk in het bronbestand ligt en waar het op de
doorlopende boek-tijdlijn staat.
app/src/main/java/nl/simon/daisyspeler/data/book/Models.kt
data class AudioSegment(
val index: Int,
val sourcePath: String,
val clipStartMs: Long,
val clipEndMs: Long,
val trackStartMs: Long,
) {
val durationMs: Long
get() = max(0L, clipEndMs - clipStartMs)
}
| Veld | Voorbeeld | Wat het betekent |
index | 2 | De derde stap in de playlist. |
sourcePath | audio/part01.mp3 | Het audiobestand waarin dit stuk staat. |
clipStartMs | 120.000 | Waar het stuk in dat bestand begint. |
clipEndMs | 135.000 | Waar het stuk in dat bestand stopt. |
trackStartMs | 240.000 | Waar het stuk op de globale boek-tijdlijn begint. |
De tijdlijn in beeld
Deel 1
0:00–2:00
Deel 2
2:00–4:00
Deel 3
4:00–5:00
0:00
2:00
4:00
5:00
De speler ziet alleen deze segmenten. De inhoudsopgave wijst naar een segment en
een offset daarbinnen. Zo kan “volgende kop” naar 2:14 springen, ook al begint
het segment zelf bij 2:00.
Waarom clips samenvoegen?
Als elke clip een apart media-item werd, zou de speler bij een boek met
duizenden clips ook duizenden items moeten voorbereiden. Door aangrenzende
clips uit hetzelfde bestand samen te voegen, blijft de playlist klein. De app
voegt alleen samen als de clips echt op elkaar aansluiten (met een kleine
tolerantie van 60 milliseconden).
Terug naar een positie
De app bewaart een positie als BookPosition: het bronbestand, de
offset in dat bestand en de globale tijd. Waarom alle drie? Omdat hetzelfde
audiobestand op meerdere plekken in een boek kan terugkomen. De globale tijd
helpt de juiste herhaling te vinden; de broninformatie is een fallback als de
boekindeling is veranderd.
app/src/main/java/nl/simon/daisyspeler/data/book/Models.kt
fun segmentAtGlobal(positionMs: Long): Pair<AudioSegment, Long>? {
if (segments.isEmpty()) return null
val safe = positionMs.coerceAtLeast(0L)
val segment =
segments.firstOrNull { safe < it.trackStartMs + it.durationMs } ?: segments.last()
return segment to (safe - segment.trackStartMs)
.coerceIn(0L, segment.durationMs)
}
Dit is een halve-open interval: een positie precies op de grens hoort
bij het volgende segment. Daardoor verspringt de markering niet onverwacht bij
een hoofdstukovergang.
Wat doet de parser met rommelige boeken?
Ontbrekende eindtijd
De parser gebruikt de start van een latere clip in hetzelfde audiobestand.
Zo blijft een boek met onvolledige SMIL-bestanden toch bruikbaar.
Onleesbaar SMIL
Dat bestand wordt overgeslagen en er komt een waarschuwing bij het boek.
Andere SMIL-bestanden kunnen gewoon doorgaan.
Geen navigatiepunten
De app maakt dan zelf “Deel 1”, “Deel 2”, enzovoort op basis van de
audiobestanden. Zo heeft de speler altijd een inhoudsopgave.
Andere tekstcodering
TextDecoding herkent een BOM of charset en valt terug op
Windows-1252 als een oud bestand niet geldig UTF-8 is.
Waarom al die waarschuwingen?
De parser wil niet meteen stoppen bij elk raar bestand. Een boek met één
onleesbaar SMIL-bestand is vaak nog steeds bruikbaar. De waarschuwingen
bewaren wat er misging, zonder de gebruiker met technische details te
overstelpen. In de UI worden ze niet standaard getoond.
Waar zoekt de app?
- Een omslag die in
book.opf staat.
- Een omslag die in
ncc.html wordt genoemd of als eerste afbeelding staat.
- Een afbeelding met een naam als
cover.jpg, omslag.png of voorblad.jpg.
- Als er precies één afbeelding is, die afbeelding.
- Een hoes die in de ID3-tags van een MP3-bestand zit.
Alleen echte bitmapformaten tellen mee: JPG, PNG, GIF, WebP en BMP. Een SVG of
een willekeurig bestand met de naam “cover” wordt niet als omslag gebruikt.
Waarom een lokale kopie?
Een mapimport leeft achter een Android-toestemming. Die toestemming kan
verdwijnen of de map kan verplaatst worden. Daarom kopieert
BookRepository de omslag naar files/covers/. De
bibliotheek blijft dan een afbeelding houden, ook als het boek tijdelijk niet
leesbaar is.
app/src/main/java/nl/simon/daisyspeler/data/BookRepository.kt (idee)
// De omslag krijgt een unieke naam.
val target = File(
coversRoot,
"$bookId-${System.currentTimeMillis()}-${System.nanoTime()}.$extension"
)
target.outputStream().use { it.write(bytes) }
libraryRepository.updateCover(bookId, target.absolutePath)
De unieke naam is bewust gekozen: als je een nieuwe omslag kiest met dezelfde
bestandsnaam, kan Compose anders nog de oude bitmap uit zijn cache tonen. Een
nieuwe naam dwingt een nieuwe afbeelding af.
Zelf een omslag kiezen
Via het afbeeldingsicoon opent een kleine browser met Google Afbeeldingen. De
zoekopdracht bestaat uit titel en auteur. Houd een afbeelding ingedrukt, bekijk
de preview en bevestig. Daarna downloadt CoverImageDownloader
alleen die afbeelding en slaat BookRepository.setCover haar op.
- Alleen HTTP(S)-links, protocol-relatieve links en
data:-afbeeldingen.
- Maximaal 12 MB en alleen bekende bitmapformaten.
- Bij een fout blijft de oude omslag staan.
- De gekozen afbeelding wordt lokaal bewaard, niet elke keer opnieuw gedownload.
Geen omslag?
Dan toont de app het standaard boek-icoon. Je kunt later altijd nog een
omslag kiezen via de omslagbrowser. Daarvoor is wel internet nodig.
Neem hier de tijd voor
Dit is het grootste en meest verweven deel van de app. Lees eerst de grote
lijn. Sla gerust de details over en kom later terug als je een specifieke
vraag hebt, bijvoorbeeld: “wat gebeurt er als ik mijn koptelefoon losmaak?”
Twee werelden
Schermwereld
PlayerViewModel
- Hoort bij het spelerscherm.
- Leest het boek uit de repository.
- Maakt verbinding met de service.
- Toont tijd, hoofdstuk, knoppen en fouten.
- Verdwijnt als het scherm definitief weg is.
Achtergrondwereld
DaisyPlaybackService
- Bezit de echte ExoPlayer.
- Blijft draaien als de app op de achtergrond staat.
- Beheert de media-melding en hoofdtelefoonknoppen.
- Bewaart de positie en bookmarks.
- Kan het laatst gespeelde boek hervatten.
De twee werelden praten via Media3. De service maakt een
MediaSession. Het scherm maakt een MediaController.
Die controller kan standaard play, pause en zoeken, en de app heeft een paar
eigen opdrachten toegevoegd, zoals LOAD_BOOK en
SET_SLEEP_TIMER. De service zet haar laadstatus in de
session extras; de ViewModel leest die extras en vertaalt ze naar de
toestand van het scherm.
De media-items
De service vertaalt elk AudioSegment naar een
MediaItem. Daarbij zegt hij: “gebruik dit audiobestand, maar alleen
het stuk tussen deze begin- en eindtijd”.
app/src/main/java/nl/simon/daisyspeler/playback/DaisyPlaybackService.kt (ingekort)
MediaItem.Builder()
.setUri(Uri.parse(source.playableUri(segment.sourcePath)))
.setMediaId("$bookId:${segment.index}")
.setClippingConfiguration(
MediaItem.ClippingConfiguration.Builder()
.setStartPositionMs(segment.clipStartMs)
.setEndPositionMs(segment.clipEndMs)
.build()
)
.build()
De mediaId begint met het boek-ID. Daaraan kan de app zien of de
media in de speler bij dít boek horen. Dat is belangrijk wanneer een oude
opdracht of een oud boek nog even doorwerkt.
De laadstatus
De service publiceert vier standen: IDLE, LOADING,
READY en ERROR. Het scherm heeft daarnaast eigen fasen
voor de laadtekst: verbinden, boek inlezen, speler voorbereiden, klaar of fout.
| Status | Betekenis | Wat de gebruiker ziet |
IDLE | Er is geen boek actief in de speler. | Bibliotheek of een leeg speler-scherm. |
LOADING | De service is een boek aan het klaarzetten. | Laadscherm met de titel en een voortgangsindicator. |
READY | De media staan echt in de speler. | Het speler-scherm met bediening. |
ERROR | Het boek kon niet worden geopend. | Een foutmelding en “Opnieuw proberen”. |
Waarom is READY pas laat?
Een service kan “klaar” roepen voordat de media echt in de speler staan. Als
de UI dan al het spelerscherm toont, krijg je een scherm zonder audio. Daarom
controleert de app of de media-items van dit boek aanwezig zijn. Is dat niet
zo, dan probeert ze het één keer opnieuw en daarna wordt het een duidelijke
fout in plaats van een oneindige spinner. Die bewaking zit in
PlayerLoadStateMachine, een klein testbaar onderdeel van de
ViewModel.
Play, pause en zoeken
De ViewModel stuurt geen ruwe speleropdrachten naar ExoPlayer. Hij stuurt een
commando naar de service. De service beslist wat dat betekent. Bij play doet hij
bijvoorbeeld meer dan alleen play():
- Is het boek klaar (ENDED)? Eerst terug naar het begin.
- Is de speler in een fout- of idle-toestand? Eerst
prepare().
- Is er een slaaptimer-fade bezig? Die wordt geannuleerd.
- Is de audiofocus tijdelijk verloren? Eerst opnieuw focus aanvragen.
- Daarna wordt één startbookmark gemaakt en gaat het afspelen verder.
Hoofdstukken en snelheid
Vorige en volgende kop gebruiken headingTarget uit
DaisyBook. Dat zoekt het dichtstbijzijnde navigatiepunt vooruit of
achteruit. De afspeelsnelheid loopt van 0,5× tot 2,0× in stappen van 0,1×. De
toonhoogte blijft gelijk; alleen het tempo verandert. De gekozen snelheid wordt
in SharedPreferences bewaard.
Audiofocus en koptelefoons
Android regelt welke app audio mag afspelen. Als een andere app de audio overneemt,
kan DaisySpeler tijdelijk of blijvend naar de achtergrond gaan. De service luistert
naar die gebeurtenissen en past de status aan.
- Bij een losgekoppelde koptelefoon of Bluetooth-speaker pauzeert de app.
- Bij tijdelijk focusverlies blijft de luistersessie kloppen: er wordt een stopbookmark gemaakt en bij hervatten een nieuwe start.
- Een expliciete tik op play vraagt opnieuw om audiofocus.
- De media-melding en headsetknoppen gebruiken dezelfde service.
- Een play-toets op een headset of auto kan het laatst gespeelde boek hervatten, ook als de app niet meer actief is.
De slaaptimer
De timer bewaart een eindtijd, niet alleen “nog zoveel minuten”. Daardoor klopt
hij ook als de app even op de achtergrond staat. De service controleert elke
seconde. Bij het verlopen fadet het volume in drie seconden naar nul, pauzeert
de audio en wordt een bookmark met reden SLEEP_TIMER opgeslagen.
app/src/main/java/nl/simon/daisyspeler/data/storage/SleepTimerManager.kt (ingekort)
val value = SleepTimerState(
bookId = bookId,
deadlineEpochMs = now + durationMs,
durationMs = durationMs,
startedAtEpochMs = now,
)
_state.value = value
persist(SleepTimerData(value))
De timer geldt per boek. Open je een ander boek, dan wordt een timer van het
oude boek geannuleerd. In debugbuilds bestaat een testoptie van 10 seconden.
Positie bewaren
Tijdens het afspelen wordt elke 30 seconden een positie bewaard. Bij pauzeren,
zoeken, stoppen en het einde van een boek gebeurt dat direct. De schrijfacties
gaan via één wachtrij, zodat een oude positie nooit een nieuwere positie
overschrijft. Bij het afsluiten krijgt die wachtrij maximaal twee seconden om
klaar te zijn.
Boekwissel
Ga je terug naar de bibliotheek, dan stuurt de navigatie een
STOP_FOR_BOOK_SWITCH-intentie. De service maakt een stopbookmark
met reden “boekwissel”, stopt de speler en ruimt de media op. Zo kan een volgend
boek veilig laden zonder dat de oude media in de weg zitten.
De lastigste wedstrijd: oude antwoorden
Stel: je tikt op boek A, daarna snel op boek B. De service kan nog bezig zijn met
A. Zonder maatregelen zou een laat antwoord van A het scherm van B kunnen
overschrijven. Daarom gebruikt de app request-id's en een
generation-teller. Een antwoord dat niet bij de nieuwste
aanvraag hoort, wordt genegeerd.
Dit lijkt misschien overdreven, maar het is precies het soort probleem dat je
anders alleen op een langzame telefoon of tijdens een grote import ziet. De
tests in BookLoadingTest.kt en de Android-tests controleren dit
gedrag.
Twee soorten bookmarks
Automatische sessies
Elke keer dat het afspelen start, opent de app een sessie. Bij pauzeren,
slapen, het einde van het boek, een fout of een boekwissel wordt de sessie
gesloten. De stopreden wordt bewaard.
Eigen bookmarks
Met “Markeren” bewaar je de huidige plek, eventueel met een korte notitie.
Deze staan boven de automatische bookmarks en kun je apart verwijderen.
app/src/main/java/nl/simon/daisyspeler/data/storage/StorageModels.kt
data class BookmarkSession(
val id: String,
val bookId: String,
val start: BookmarkPoint,
val stop: BookmarkPoint? = null,
)
data class ManualBookmark(
val id: String,
val bookId: String,
val point: BookmarkPoint,
val note: String? = null,
)
Een BookmarkPoint bewaart dezelfde drie positiegegevens als
BookPosition, plus een label, tijdstip en optionele reden. Daardoor
kan de app later terugspringen, ook als de boekindeling licht is veranderd.
Waarom een sessie en geen losse bookmark?
Een luistersessie heeft een begin en een eind. Door ze als paar te bewaren, kan
de app later tonen hoe lang je hebt geluisterd en waar je bent gestopt. De
stopreden maakt het verschil tussen “zelf gepauzeerd”, “slaaptimer”, “einde
boek” en “fout” zichtbaar.
Opruimen
- Maximaal vijf automatische sessies per boek.
- Maximaal 200 eigen bookmarks per boek.
- Een sessie die langer dan twaalf uur openstaat, wordt als verouderd (
STALE) gesloten.
- Bij verwijderen van een boek verdwijnen alle bookmarks van dat boek.
Verder luisteren is iets anders
“Verder luisteren” is de laatste positie in LibraryEntry.lastPosition.
Die wordt tijdens het afspelen en bij zoeken/pauzeren bijgewerkt. Een bookmark is
een expliciet moment; de laatste positie is simpelweg waar de speler moet
hervatten. Ze worden apart opgeslagen en hebben een verschillend doel.
Waarom zowel bron- als globale positie?
Een boek kan hetzelfde audiobestand meerdere keren gebruiken, bijvoorbeeld
bij een herhaling. De bronpositie alleen is dan dubbelzinnig. De globale
positie helpt de juiste herhaling te vinden. Andersom kan een gewijzigde
boekindeling de globale positie minder betrouwbaar maken; dan is de
bronpositie weer nuttig.
Welke websites?
De app ondersteunt twee vaste websites: Passend Lezen en
ABC Global Books. Je logt in met je eigen account. De browser
is geen algemene browser: hij is bedoeld voor deze websites en hun downloads.
De downloadreis
-
1
Downloadlink
De WebView ziet een download en geeft de URL, cookies en user-agent door.
-
2
DownloadManager
Android downloadt naar
Download/audioboeken en gaat door als de app op de achtergrond staat.
-
3
Melding
Bij voltooiing of bij terugkeer in de app controleert de monitor de download.
-
4
Importeren
Alleen een ZIP-bestand wordt automatisch uitgepakt en aan de bibliotheek toegevoegd.
Waarom DownloadManager?
DownloadManager wordt door Android beheerd. Een grote download kan
daardoor doorlopen als de app naar de achtergrond gaat of tijdelijk wordt
afgesloten. De app hoeft dan geen eigen achtergrondproces voor het downloaden
open te houden.
Map en toestemming
Standaard gaan downloads naar Download/audioboeken. De naam is in de
app aan te passen. Op Android 10 en nieuwer regelt de app de map via MediaStore,
zonder brede opslagtoestemming. Op Android 9 en ouder is
WRITE_EXTERNAL_STORAGE nodig.
Automatische import
De app bewaart welke download-ID's nog verwerkt moeten worden. Een voltooide
download wordt op meerdere momenten gecontroleerd:
- bij het starten van de app;
- als Android een “download voltooid”-melding stuurt;
- als je terugkeert in de app;
- als je zelf op “Toevoegen” tikt.
Een download die geen ZIP is, blijft in de downloadmap staan. De app meldt dat
alleen ZIP-bestanden automatisch worden toegevoegd. Een mislukte import wordt
maximaal drie keer opnieuw geprobeerd.
ZIP controleren zonder hem eerst te openen
De app leest de eerste twee bytes van het gedownloade bestand. Als dat
P en K zijn, is het waarschijnlijk een ZIP. Zo voorkomt
de app dat een willekeurig bestand als boek wordt uitgepakt.
Geen dubbele downloads
DownloadEnqueueGuard onthoudt welke URL en bestandsnaam al
onderweg zijn. Tik je twee keer op dezelfde download, dan meldt de app dat het
boek al gedownload wordt of nog aan de bibliotheek wordt toegevoegd.
Wat verlaat je toestel?
De boekbrowser en de omslagbrowser gebruiken internet. De rest van de app
werkt lokaal. Er is geen account bij DaisySpeler zelf en er worden geen
luistergegevens naar een server gestuurd.
De vijf schermen
▤
Bibliotheek
Boekenplank, sorteren, importeren, omslagen, downloaden en verwijderen.
ui/library/LibraryScreen.kt
◉
Speler
Omslag, titel, hoofdstuk, tijdlijn, play/pause, snelheid, timer en bookmarks.
ui/player/PlayerScreen.kt
⌕
Omslagbrowser
Google Afbeeldingen met een zoekveld en een lange-vingerige preview.
ui/cover/CoverBrowserScreen.kt
⌂
Boekbrowser
WebView voor de twee boekwebsites, met downloadmap en voortgang.
ui/browser/BookBrowserScreen.kt
ⓘ
Over
Auteur, versie, help en de GPLv3-licentie.
ui/about/AboutScreen.kt
Hoe een scherm werkt
Een scherm leest een StateFlow uit zijn ViewModel met
collectAsStateWithLifecycle. Als de waarde verandert, maakt Compose
het scherm opnieuw. De gebruiker tikt op een knop, de knop roept een functie op
het ViewModel aan, en het ViewModel verandert de toestand of stuurt een opdracht.
app/src/main/java/nl/simon/daisyspeler/ui/library/LibraryScreen.kt (ingekort)
val state by viewModel.uiState.collectAsStateWithLifecycle()
Scaffold(
topBar = { /* titel en knoppen */ },
floatingActionButton = {
ExtendedFloatingActionButton(
onClick = { showAddSheet = true },
text = { Text("Boek toevoegen") },
)
},
) { padding -> /* de boekenlijst */ }
Het speler-scherm
De speler heeft een compacte kop met omslag, titel en hoofdstuk. Daaronder
staan de tijdlijn en de bediening. Via kleine knoppen open je bottom sheets:
- Inhoud: koppen, pagina's of alles, met filters.
- Bookmarks: automatische sessies en eigen notities.
- Snelheid: van 0,5× tot 2,0×.
- Slaaptimer: 15 minuten tot 2 uur.
Het laadscherm
Bij het openen uit de bibliotheek verschijnt eerst een laadscherm met de
boektitel. De tekst volgt de laadfase: “Verbinden met de speler…”, “Boek
inlezen…” of “Speler voorbereiden…”. Zo weet je dat de app bezig is en niet
vastgelopen.
Toegankelijkheid
De app gebruikt Nederlandse contentDescription-teksten voor
iconen, een grotere icoonstand (1,5×) via de vergrootglasknop en een
Material 3-thema dat meebeweegt met licht/donker. Veel knoppen hebben ook een
stateDescription, zodat een schermlezer kan melden of iets aan of
uit staat.
Thema
Op Android 12 en nieuwer gebruikt de app dynamische kleuren van het systeem.
Op oudere versies valt ze terug op een paars palette. De app heeft geen eigen
lettertype-bestand; ze gebruikt de standaardtekst van Material 3.
| Model | Waar het voor dient | Bewaard als |
DaisyBook |
Het volledige, geparseerde boek: titel, segmenten, inhoudsopgave en omslag. |
Alleen in het geheugen (cache). |
AudioSegment |
Eén stuk audio uit één bestand, met een plek op de globale tijdlijn. |
Onderdeel van DaisyBook; niet apart opgeslagen. |
NavPoint |
Een hoofdstuk, pagina, zijbalk of notitie in de inhoudsopgave. |
Onderdeel van DaisyBook. |
BookPosition |
Een plek in het boek: bronbestand, bronoffset en globale tijd. |
In library.json en bookmarks. |
LibraryEntry |
De administratie van één boek op de boekenplank. |
library.json |
BookmarkSession |
Een automatische start/stop-sessie. |
bookmarks.json |
ManualBookmark |
Een door de gebruiker gemaakte bookmark, met optionele notitie. |
bookmarks.json |
BookmarkPoint |
De positie en het tijdstip van een bookmark. |
Onderdeel van bookmarks. |
SleepTimerState |
Voor welk boek de timer loopt en wanneer hij afloopt. |
sleep_timer.json |
PlaybackUiState |
Alles wat het speler-scherm op dit moment moet tonen. |
Alleen in het geheugen. |
PlayerLoadSnapshot |
De fase van één laadpoging, met request-id en eventuele fout. |
Alleen in het geheugen. |
Waarom JSON en geen database?
De app bewaart een beperkte hoeveelheid gegevens: een bibliotheek, bookmarks,
een timer en een paar voorkeuren. JSON-bestanden zijn dan eenvoudig te lezen,
te testen en te back-uppen. De keerzijde is dat elke wijziging het hele bestand
opnieuw schrijft. Daarom worden posities niet bij elke seconde weggeschreven,
maar met tussenpozen en op belangrijke momenten.
Atomic schrijven
JsonFileStore schrijft eerst naar bestand.tmp en
hernoemt dat daarna naar het echte bestand. Wordt de app halverwege
afgesloten, dan is de kans kleiner dat het originele bestand half beschreven
achterblijft.
Twee soorten tijd
In de code kom je twee soorten tijd tegen:
- Positietijd in milliseconden, bijvoorbeeld
globalMs of trackStartMs.
- Kloktijd in epoch-milliseconden, bijvoorbeeld
createdAtEpochMs of deadlineEpochMs.
Positietijd zegt “hoe ver in het boek”; kloktijd zegt “wanneer op de kalender”.
Ze door elkaar halen is een klassieke programmeerfout.
| Bestand | Wat het doet | Niveau |
DaisyApplication.kt | Start de app en maakt de container. | Makkelijk |
AppContainer.kt | Maakt repositories, import, download en timer. | Makkelijk |
MainActivity.kt | Start Compose en vraagt meldingstoestemming. | Makkelijk |
Navigation.kt | Koppelt routes aan schermen. | Makkelijk |
data/book/Models.kt | Boek, segment, navigatiepunt en positie. | Makkelijk |
data/BookRepository.kt | Laden, cachen, importeren en omslagen beheren. | Gevorderd |
data/BookImporter.kt | Import + bibliotheekentry in één stap. | Makkelijk |
data/parser/DaisyBookLoader.kt | Het complete DAISY-boek opbouwen. | Gevorderd |
data/parser/NccParser.kt | Inhoudsopgave en metadata uit ncc.html. | Gemiddeld |
data/parser/OpfParser.kt | Metadata en SMIL-volgorde uit book.opf. | Gemiddeld |
data/parser/SmilParser.kt | Audio- en tekstkoppelingen uit SMIL. | Gemiddeld |
data/parser/PathUtils.kt | Paden normaliseren en URL's oplossen. | Gemiddeld |
data/parser/TimeParser.kt | npt=-tijden omzetten naar milliseconden. | Makkelijk |
data/parser/TextDecoding.kt | BOM, UTF-8 en Windows-1252 herkennen. | Gemiddeld |
data/parser/ImageFiles.kt | Bitmapformaten en omslagnamen herkennen. | Makkelijk |
data/parser/EmbeddedCover.kt | Omslag uit ID3-tags van audio halen. | Gevorderd |
data/importer/ZipBookExtractor.kt | Veilig ZIP-bestanden uitpakken. | Gemiddeld |
data/source/BookSource.kt | De gedeelde interface voor boekmappen. | Makkelijk |
data/source/SafBookSource.kt | Een map via Android SAF lezen. | Gemiddeld |
data/source/FileBookSource.kt | Een uitgepakte map in app-opslag lezen. | Makkelijk |
data/storage/JsonFileStore.kt | JSON atomisch lezen en schrijven. | Makkelijk |
data/storage/LibraryRepository.kt | De boekenlijst beheren. | Gemiddeld |
data/storage/BookmarkRepository.kt | Sessies en handmatige bookmarks beheren. | Gemiddeld |
data/storage/SleepTimerManager.kt | De slaaptimer starten, stoppen en bewaren. | Makkelijk |
data/storage/UiPreferences.kt | Grote iconen en downloadmap bewaren. | Makkelijk |
data/download/AudiobookDownloads.kt | DownloadManager, mappen en import volgen. | Gevorderd |
data/download/DownloadImportMonitor.kt | Importchecks in de achtergrond starten. | Gemiddeld |
data/website/AudiobookSite.kt | De twee ondersteunde boekwebsites. | Makkelijk |
data/cover/CoverImageDownloader.kt | Een gekozen omslagafbeelding downloaden. | Gemiddeld |
playback/DaisyPlaybackService.kt | ExoPlayer, MediaSession, bookmarks en timer. | Gevorderd |
playback/PlaybackCommands.kt | De namen van extra service-opdrachten. | Makkelijk |
playback/PlaybackStorage.kt | Opslagopdrachten in de juiste volgorde uitvoeren. | Gemiddeld |
playback/PlaybackSpeedOptions.kt | Toegestane afspeelsnelheden controleren. | Makkelijk |
ui/library/LibraryViewModel.kt | Importeren, verwijderen, sorteren en omslagen. | Gemiddeld |
ui/library/LibraryScreen.kt | De boekenplank en alle bibliotheekknoppen. | Gemiddeld |
ui/player/PlayerViewModel.kt | Verbinden met de service en de UI-status bijhouden. | Gevorderd |
ui/player/PlayerScreen.kt | Het speler-scherm en de bottom sheets. | Gevorderd |
ui/player/PlayerLoadState.kt | De laadfasen en timeouts als testbare state machine. | Gevorderd |
ui/components/BookCover.kt | Een omslag of het standaard-icoon tonen. | Makkelijk |
ui/theme/Theme.kt | Licht/donker en dynamische kleuren. | Makkelijk |
ui/theme/IconScale.kt | De schaal voor grote iconen. | Makkelijk |
util/Format.kt | Tijd, timer en datum leesbaar maken. | Makkelijk |
Waar staan de gebruikersgegevens?
| Plek | Inhoud |
files/library.json | Boekenlijst, laatste positie en het moment waarop elk boek is toegevoegd. |
files/bookmarks.json | Automatische sessies en handmatige bookmarks. |
files/sleep_timer.json | De actieve slaaptimer, als die er is. |
files/books/<id>/ | Uitgepakte ZIP-boeken. |
files/covers/ | Lokale omslagafbeeldingen. |
| SharedPreferences | Interface-instellingen, laatste boek, snelheid, downloadmap en wachtende downloads. |
Download/audioboeken/ | Gedownloade ZIP-bestanden, gedeeld met de gebruiker. |
Lokaal draaien
In de hoofdmap van het project
./gradlew :app:testDebugUnitTest :app:assembleDebug :app:lintDebug
De debug-APK komt daarna in
app/build/outputs/apk/debug/app-debug.apk.
Wat testen ze?
Parser
NCC, OPF, SMIL, paden, tekstcodering, tijdnotatie en ontbrekende eindtijden.
Opslag
Bibliotheek, bookmarks, slaaptimer, JSON-behoud en schrijffouten.
Import en download
ZIP-beveiliging, downloadstatussen, mappen en dubbele downloads.
Speler
Laadstatus, timeouts, snelheid, bookmarks en positieherstel.
Android-tests
Een deel van de tests heeft een emulator of toestel nodig. Ze gebruiken een
lokaal gegenereerd WAV-boek en een apart applicationId, zodat je
eigen boeken en accounts niet worden overschreven.
Android-tests met een aparte testinstallatie
./gradlew :app:connectedDebugAndroidTest \
-I gradle/isolated-tests.init.gradle --no-configuration-cache
Daarna bouw je met :app:assembleDebug weer een normale APK. De
volledige afspraken staan in docs/regression-tests.md.
Tests als leesroute
Wil je weten hoe een laadfout wordt afgehandeld? Lees
BookLoadingTest.kt. Wil je begrijpen hoe een bookmark wordt
geopend en gesloten? Lees BookmarkRepositoryTest.kt. Tests zijn
vaak korter en gerichter dan de productcode.
Belangrijke testbestanden
| Test | Waarover |
DaisyBookLoaderTest.kt | Volledige boekload, clips, segmenten en navigatie. |
NccParserTest.kt | NCC-metadata, koppen, pagina's en omslagen. |
SmilParserTest.kt | SMIL-clips en tijden. |
ZipBookExtractorTest.kt | Veilig uitpakken en geweigerde paden. |
LibraryRepositoryTest.kt | Toevoegen, bijwerken en verwijderen. |
BookmarkRepositoryTest.kt | Sessies, handmatige bookmarks en opschonen. |
SleepTimerManagerTest.kt | Timer starten, verlopen en bewaren. |
PlaybackStorageTest.kt | Volgorde van opslagopdrachten. |
BookLoadingTest.kt | Laadfasen, timeouts en READY zonder media. |
PlaybackRegressionTest.kt | Echte afspeelsituaties op een toestel of emulator. |
- Activity
- Een Android-onderdeel met een scherm. Hier is dat
MainActivity.
- Application
- Het object dat Android één keer per app-proces maakt. Hier ontstaat de container.
- Compose
- De manier waarop deze app schermen bouwt: met Kotlin-functies in plaats van XML-layouts.
- ViewModel
- Een object dat de toestand van een scherm vasthoudt en acties uitvoert. Overleeft een schermrotatie.
- StateFlow
- Een houder met een actuele waarde waar schermen automatisch naar kunnen luisteren.
- Coroutine
- Een lichtgewicht taak die kan wachten zonder het hele programma te blokkeren.
suspend betekent: “deze functie mag wachten”.
- Repository
- De plek die gegevens ophaalt en bewaart. De UI hoeft niet te weten hoe dat gebeurt.
- Service
- Een Android-onderdeel dat zonder scherm kan draaien. De playback-service bezit de speler.
- Media3 / ExoPlayer
- De Android-bibliotheek die audio afspeelt en mediasessies beheert.
- MediaSession
- De brug tussen de speler en de buitenwereld: melding, vergrendelscherm, headset en controller.
- MediaController
- De afstandsbediening waarmee een scherm opdrachten naar de media-sessie stuurt.
- DAISY 2.02
- Het luisterboekformaat dat deze app ondersteunt.
- NCC
ncc.html: de inhoudsopgave en metadata van een DAISY-boek.
- OPF
book.opf: een optionele beschrijving van de bestanden en hun volgorde.
- SMIL
- Een bestand dat tekstfragmenten aan audioclips koppelt.
- Clip
- Een stuk audio met een begin- en eindtijd binnen één audiobestand.
- Segment
- Een samengevoegd stuk audio op de doorlopende tijdlijn van het boek.
- SAF
- Storage Access Framework: de Android-manier om toegang te vragen tot precies de map die de gebruiker kiest.
- URI
- Een verwijzing naar een bestand of map, bijvoorbeeld
content://....
- JSON
- Een tekstformaat om gegevens te bewaren. De bibliotheek en bookmarks staan erin.
- SharedPreferences
- Kleine Android-opslag voor instellingen, zoals de gekozen sorteervolgorde.
- Gradle
- Het bouwsysteem dat de app compileert en tests start.
- APK
- Het installeerbare bestand van een Android-app.
-
Dag 1 — De voordeur.
Lees
AndroidManifest.xml, DaisyApplication.kt,
AppContainer.kt en MainActivity.kt. Vraag: welke
objecten bestaan er voordat het eerste scherm verschijnt?
-
Dag 2 — De boekenplank.
Lees
LibraryScreen.kt, LibraryViewModel.kt,
LibraryRepository.kt en StorageModels.kt. Vraag:
hoe komt een boek in de lijst en hoe wordt de lijst bewaard?
-
Dag 3 — Het boek binnenhalen.
Lees
BookImporter.kt, BookRepository.importZip en
ZipBookExtractor.kt. Vraag: wat gebeurt er als een ZIP onveilig
of onvolledig is?
-
Dag 4 — Het boek begrijpen.
Lees
Models.kt, daarna DaisyBookLoader.kt. Vraag:
hoe wordt één losse clip een segment op de globale tijdlijn?
-
Dag 5 — De speler.
Lees
PlaybackCommands.kt, PlayerLoadState.kt,
PlayerViewModel.kt en daarna de grote lijnen van
DaisyPlaybackService.kt. Vraag: waarom bestaat de service los
van het scherm?
-
Dag 6 — Onthouden en doorgaan.
Lees
BookmarkRepository.kt, SleepTimerManager.kt en
de bookmarkfuncties in de service. Vraag: wat is het verschil tussen een
bookmark en “verder luisteren”?
-
Dag 7 — Vertrouwen.
Kies drie tests uit
app/src/test en lees ze. Vraag: welke
situatie zou zonder deze test stukgaan?
Vijf kleine oefeningen
1
Zoek de titel
Waar wordt de titel van een boek uit ncc.html gelezen en waar komt die op het scherm?
2
Volg een bookmark
Begin bij “Markeren” in PlayerScreen.kt en volg de route tot in BookmarkRepository.kt.
3
Lees een foutmelding
Zoek de tekst “Het boek kon niet op tijd worden geopend” en lees welke time-out daarbij hoort.
4
Maak een tijdlijn
Bedenk drie clips met verschillende bronbestanden en teken de globale tijdlijn. Waar begint segment 3?
5
Lees een test
Open BookLoadingTest.kt. Welke drie situaties worden daar getest?
Debuggen zonder verdwalen
- Gebruik Logcat en filter op
DaisyPlayback, DaisyPlayer of DaisyLibrary.
- Zoek in de code op een unieke fouttekst uit de UI of uit een logregel.
- Lees bij een crash eerst de bovenste regels van de stacktrace, niet de hele lijst.
- Test met een klein boek voordat je een groot boek probeert.
- Verander één ding tegelijk en draai daarna de tests.
Je hoeft niet alles te begrijpen
Goede code leest als een reeks kleine beslissingen. Als een bestand te groot
voelt, zoek dan één functie die je wél begrijpt en volg van daaruit de
aanroepen. De rest komt later.
Verder lezen