Codeboek · mainbranch · versie 6.0

DaisySpeler
van binnenuit

Van de eerste tik op een boek tot de laatste noot: lees hoe deze Android-app in elkaar zit. In gewone taal, met kleine stukjes code en veel verwijzingen naar de echte bestanden.

  • Kotlin
  • Jetpack Compose
  • Media3
  • 59 Kotlin-bestanden
  • main @ 8a1fe33

Geschreven op 28 oktober 2026. De code is de bron; dit boek is de kaart.

Het DaisySpeler-app-icoon: een madeliefje met een play-knop in het hart.
DaisySpeler Een eenvoudige luisterspeler voor DAISY 2.02-boeken.

01

Begin hier

Start hier

Je hoeft geen Android-expert te zijn om deze code te begrijpen. Dit boek begint bij wat de app doet en zoomt daarna steeds een laag dieper in.

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

  1. 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.
  2. Volg één actie. Kies bijvoorbeeld “een boek openen” en volg die route door de bestanden. Dat werkt beter dan alle bestanden op alfabet lezen.
  3. Kijk naar de codefragmenten. Ze zijn kort en komen uit de echte code. De bestandsnaam staat erboven, zodat je verder kunt zoeken.
  4. 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.

02

Het grote plaatje

Een bibliotheek met een geluidsstudio

De app bestaat uit vier duidelijke rollen. Als je die uit elkaar houdt, wordt de code veel minder eng.

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

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?

BestandWat het isWat de app ermee doet
ncc.htmlInhoudsopgave en informatie over het boek.Titel, auteur, taal, navigatiepunten en omslag lezen.
book.opfOptionele pakketbeschrijving.Extra metadata, volgorde van SMIL-bestanden en omslaginformatie lezen.
*.smilKoppeling tussen een stuk tekst en een stuk audio.Per <par> lezen welke audio wanneer start en stopt.
*.mp3, *.wavDe echte audio.Als playlist aan ExoPlayer geven, met begin- en eindpunt per segment.
AfbeeldingenOmslag of illustraties.Omslag opsporen en lokaal bewaren.

De reis van één boek

  1. 1 Kiezen De gebruiker tikt op een boek in de bibliotheek.
  2. 2 Laden De repository leest het boek en de parser maakt een DaisyBook.
  3. 3 Klaarzetten De service bouwt media-items en zet de speler op de opgeslagen positie.
  4. 4 Spelen ExoPlayer speelt de segmenten als één doorlopende lijst af.
  5. 5 Onthouden Positie en bookmarks worden lokaal opgeslagen.

03

De plattegrond

Waar staat wat?

De mappen volgen de belangrijkste vraag van de app: waar komt een boek vandaan, hoe wordt het gelezen en hoe klinkt het?

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

MapRolBeginnerstip
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.

OnderdeelKeuze in dit projectWaarvoor
TaalKotlin 2.3.20De hele app, inclusief de UI.
UIJetpack Compose + Material 3Schermen als Kotlin-functies, zonder XML-layouts.
NavigatieNavigation 3Routes en de terug-stack tussen schermen.
AudioMedia3 / ExoPlayerAfspelen, mediasessies, meldingen en achtergrondbediening.
HTML en XMLjsoup + W3C DOMNCC lezen met jsoup; OPF en SMIL met de DOM-parser.
JSONkotlinx.serializationBibliotheek, bookmarks en slaaptimer bewaren.
Android-versiesminSdk 24, target/compile 36Draait op Android 7.0 en nieuwer.
BuildGradle + JDK 17Compileren, 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.

04

Van tik naar scherm

Opstarten en navigeren

Android begint niet bij het eerste scherm, maar bij de Application. Daarna maakt de app één container met alle gedeelde onderdelen.

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.

RouteSchermBijzonderheid
LibraryRouteBibliotheekStartpunt van de app.
PlayerRoute(bookId)SpelerWeet welk boek geopend moet worden.
CoverBrowserRoute(bookId)Omslag zoekenOpent Google Afbeeldingen voor één boek.
BookBrowserRoute(site)BoekbrowserOpent één van de twee ondersteunde boekwebsites.
AboutRouteOver DaisySpelerVersie, 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.

05

De boekenplank

De bibliotheek

De bibliotheek is een lijst met boekgegevens. Die lijst wordt als JSON bewaard en via een StateFlow aan de schermen gegeven.

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,
)
VeldBetekenis voor een beginner
idEen korte code die dit boek uniek maakt.
treeUriDe verwijzing naar de gekozen map of het ZIP-bestand.
title, authorWat op de boekenplank staat.
durationMsTotale luisterduur in milliseconden.
lastPositionWaar je gebleven bent: bronbestand, offset en globale tijd.
lastReadAtEpochMsWanneer je het boek voor het laatst opende; gebruikt voor sorteren.
sourceTypeMap of ZIP. Bepaalt hoe de app het boek later terugvindt.
localDirBij een ZIP: de uitgepakte map in app-eigen opslag.
coverPathPad naar de lokale omslagafbeelding.

De route door de code

  1. LibraryScreen.kt toont de boeken en de knoppen.
  2. LibraryViewModel.kt combineert de boekenlijst met de gekozen sortering.
  3. LibraryRepository.kt bewaart elke wijziging in library.json.
  4. 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:

  1. stopt het boek in de playback-service als het daar openstaat;
  2. verwijdert de bookmarks van dat boek;
  3. gooit de geparseerde versie uit het geheugen;
  4. verwijdert bij een ZIP-import de uitgepakte bestanden en de omslag;
  5. 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.

06

Van buiten naar binnen

Boeken importeren

Er zijn twee deuren naar de bibliotheek: een uitgepakte map kiezen of een ZIP-bestand kiezen. Daarachter komt alles samen in dezelfde importeur.

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.

07

Het hart van de app

Een DAISY-boek lezen

De parser verandert een map met losse aanwijzingen in één DaisyBook met een doorlopende tijdlijn en een inhoudsopgave.

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

  1. Bestanden inventariseren. De loader maakt een lijst van alle bestanden en een index waarbij hoofdletters geen verschil maken.
  2. ncc.html vinden. De app kiest de ondiepst gelegen NCC. Zonder NCC stopt de import met een duidelijke fout.
  3. NCC lezen. Titel, auteur, taal, totale tijd, navigatiepunten en een eventuele omslag komen binnen via NccParser.
  4. OPF lezen, als die er is. OpfParser levert extra metadata, de volgorde van SMIL-bestanden en soms een betere omslag.
  5. SMIL-bestanden ordenen. Eerst de OPF-spine, dan de NCC-volgorde, dan een eventueel er_book_info.xml en ten slotte de rest.
  6. 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.
  7. Segmenten bouwen. Aangrenzende clips uit hetzelfde bestand worden samengevoegd. Elk segment krijgt een plek op de globale tijdlijn.
  8. 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:

TypeBetekenis
HEADINGEen hoofdstuk of kop.
PAGEEen paginanummer uit het boek.
SIDEBAREen zijbalk of extra tekstblok.
FOOTNOTEEen voetnoot.
PRODNOTEEen producentnotitie, bijvoorbeeld over de opname.
OTHEROverige 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)
}
VeldVoorbeeldWat het betekent
index2De derde stap in de playlist.
sourcePathaudio/part01.mp3Het audiobestand waarin dit stuk staat.
clipStartMs120.000Waar het stuk in dat bestand begint.
clipEndMs135.000Waar het stuk in dat bestand stopt.
trackStartMs240.000Waar het stuk op de globale boek-tijdlijn begint.

De tijdlijn in beeld

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.

08

Een gezicht voor elk boek

Omslagen

Een omslag kan in het boek staan, in de metadata worden genoemd of in een audiobestand verstopt zitten. De app probeert ze in die volgorde.

Waar zoekt de app?

  1. Een omslag die in book.opf staat.
  2. Een omslag die in ncc.html wordt genoemd of als eerste afbeelding staat.
  3. Een afbeelding met een naam als cover.jpg, omslag.png of voorblad.jpg.
  4. Als er precies één afbeelding is, die afbeelding.
  5. 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.

09

Het ingewikkeldste deel

Afspelen

Het speler-scherm is maar een bedieningspaneel. De echte speler is een Android-service die ook zonder het scherm kan blijven draaien.

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.

StatusBetekenisWat de gebruiker ziet
IDLEEr is geen boek actief in de speler.Bibliotheek of een leeg speler-scherm.
LOADINGDe service is een boek aan het klaarzetten.Laadscherm met de titel en een voortgangsindicator.
READYDe media staan echt in de speler.Het speler-scherm met bediening.
ERRORHet 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.

10

Nooit meer de weg kwijt

Bookmarks en verder luisteren

DaisySpeler maakt automatisch een start- en stoppunt per luistersessie. Daarnaast kun je zelf een bookmark met een notitie maken.

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.

11

Boeken van het web

Boekbrowser en downloads

De ingebouwde browser opent twee boekwebsites. Een download gaat via Android's DownloadManager naar de gedeelde Download-map en wordt daarna automatisch geïmporteerd.

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. 1 Downloadlink De WebView ziet een download en geeft de URL, cookies en user-agent door.
  2. 2 DownloadManager Android downloadt naar Download/audioboeken en gaat door als de app op de achtergrond staat.
  3. 3 Melding Bij voltooiing of bij terugkeer in de app controleert de monitor de download.
  4. 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.

12

De voorkant

De schermen

Alle schermen zijn geschreven met Jetpack Compose. Een scherm is een functie die de huidige toestand omzet in knoppen, tekst en vlakken.

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.

13

De woordenschat

Datamodellen

Bijna elk bestand in de app gebruikt een van deze dataclasses. Ken je ze, dan lees je de rest een stuk sneller.

ModelWaar het voor dientBewaard 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.

14

Naslag

Bestandsgids

Dit zijn de bestanden waar je het vaakst zult kijken. De moeilijkheidsgraad is een ruwe indicatie, geen wedstrijd.

BestandWat het doetNiveau
DaisyApplication.ktStart de app en maakt de container.Makkelijk
AppContainer.ktMaakt repositories, import, download en timer.Makkelijk
MainActivity.ktStart Compose en vraagt meldingstoestemming.Makkelijk
Navigation.ktKoppelt routes aan schermen.Makkelijk
data/book/Models.ktBoek, segment, navigatiepunt en positie.Makkelijk
data/BookRepository.ktLaden, cachen, importeren en omslagen beheren.Gevorderd
data/BookImporter.ktImport + bibliotheekentry in één stap.Makkelijk
data/parser/DaisyBookLoader.ktHet complete DAISY-boek opbouwen.Gevorderd
data/parser/NccParser.ktInhoudsopgave en metadata uit ncc.html.Gemiddeld
data/parser/OpfParser.ktMetadata en SMIL-volgorde uit book.opf.Gemiddeld
data/parser/SmilParser.ktAudio- en tekstkoppelingen uit SMIL.Gemiddeld
data/parser/PathUtils.ktPaden normaliseren en URL's oplossen.Gemiddeld
data/parser/TimeParser.ktnpt=-tijden omzetten naar milliseconden.Makkelijk
data/parser/TextDecoding.ktBOM, UTF-8 en Windows-1252 herkennen.Gemiddeld
data/parser/ImageFiles.ktBitmapformaten en omslagnamen herkennen.Makkelijk
data/parser/EmbeddedCover.ktOmslag uit ID3-tags van audio halen.Gevorderd
data/importer/ZipBookExtractor.ktVeilig ZIP-bestanden uitpakken.Gemiddeld
data/source/BookSource.ktDe gedeelde interface voor boekmappen.Makkelijk
data/source/SafBookSource.ktEen map via Android SAF lezen.Gemiddeld
data/source/FileBookSource.ktEen uitgepakte map in app-opslag lezen.Makkelijk
data/storage/JsonFileStore.ktJSON atomisch lezen en schrijven.Makkelijk
data/storage/LibraryRepository.ktDe boekenlijst beheren.Gemiddeld
data/storage/BookmarkRepository.ktSessies en handmatige bookmarks beheren.Gemiddeld
data/storage/SleepTimerManager.ktDe slaaptimer starten, stoppen en bewaren.Makkelijk
data/storage/UiPreferences.ktGrote iconen en downloadmap bewaren.Makkelijk
data/download/AudiobookDownloads.ktDownloadManager, mappen en import volgen.Gevorderd
data/download/DownloadImportMonitor.ktImportchecks in de achtergrond starten.Gemiddeld
data/website/AudiobookSite.ktDe twee ondersteunde boekwebsites.Makkelijk
data/cover/CoverImageDownloader.ktEen gekozen omslagafbeelding downloaden.Gemiddeld
playback/DaisyPlaybackService.ktExoPlayer, MediaSession, bookmarks en timer.Gevorderd
playback/PlaybackCommands.ktDe namen van extra service-opdrachten.Makkelijk
playback/PlaybackStorage.ktOpslagopdrachten in de juiste volgorde uitvoeren.Gemiddeld
playback/PlaybackSpeedOptions.ktToegestane afspeelsnelheden controleren.Makkelijk
ui/library/LibraryViewModel.ktImporteren, verwijderen, sorteren en omslagen.Gemiddeld
ui/library/LibraryScreen.ktDe boekenplank en alle bibliotheekknoppen.Gemiddeld
ui/player/PlayerViewModel.ktVerbinden met de service en de UI-status bijhouden.Gevorderd
ui/player/PlayerScreen.ktHet speler-scherm en de bottom sheets.Gevorderd
ui/player/PlayerLoadState.ktDe laadfasen en timeouts als testbare state machine.Gevorderd
ui/components/BookCover.ktEen omslag of het standaard-icoon tonen.Makkelijk
ui/theme/Theme.ktLicht/donker en dynamische kleuren.Makkelijk
ui/theme/IconScale.ktDe schaal voor grote iconen.Makkelijk
util/Format.ktTijd, timer en datum leesbaar maken.Makkelijk

Waar staan de gebruikersgegevens?

PlekInhoud
files/library.jsonBoekenlijst, laatste positie en het moment waarop elk boek is toegevoegd.
files/bookmarks.jsonAutomatische sessies en handmatige bookmarks.
files/sleep_timer.jsonDe actieve slaaptimer, als die er is.
files/books/<id>/Uitgepakte ZIP-boeken.
files/covers/Lokale omslagafbeeldingen.
SharedPreferencesInterface-instellingen, laatste boek, snelheid, downloadmap en wachtende downloads.
Download/audioboeken/Gedownloade ZIP-bestanden, gedeeld met de gebruiker.

15

Vertrouwen in de code

Tests

De tests zijn een tweede handleiding: ze laten zien welke situaties de ontwikkelaars belangrijk vinden.

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

TestWaarover
DaisyBookLoaderTest.ktVolledige boekload, clips, segmenten en navigatie.
NccParserTest.ktNCC-metadata, koppen, pagina's en omslagen.
SmilParserTest.ktSMIL-clips en tijden.
ZipBookExtractorTest.ktVeilig uitpakken en geweigerde paden.
LibraryRepositoryTest.ktToevoegen, bijwerken en verwijderen.
BookmarkRepositoryTest.ktSessies, handmatige bookmarks en opschonen.
SleepTimerManagerTest.ktTimer starten, verlopen en bewaren.
PlaybackStorageTest.ktVolgorde van opslagopdrachten.
BookLoadingTest.ktLaadfasen, timeouts en READY zonder media.
PlaybackRegressionTest.ktEchte afspeelsituaties op een toestel of emulator.

16

Naslag

Woordenboek

Kort genoeg om even te checken, precies genoeg om verder te kunnen.

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.

17

Aan de slag

Een leesroute voor beginners

Je hoeft niet alle 59 bestanden te lezen. Deze route geeft je steeds één vraag om te beantwoorden.

  1. Dag 1 — De voordeur. Lees AndroidManifest.xml, DaisyApplication.kt, AppContainer.kt en MainActivity.kt. Vraag: welke objecten bestaan er voordat het eerste scherm verschijnt?
  2. 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?
  3. Dag 3 — Het boek binnenhalen. Lees BookImporter.kt, BookRepository.importZip en ZipBookExtractor.kt. Vraag: wat gebeurt er als een ZIP onveilig of onvolledig is?
  4. Dag 4 — Het boek begrijpen. Lees Models.kt, daarna DaisyBookLoader.kt. Vraag: hoe wordt één losse clip een segment op de globale tijdlijn?
  5. 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?
  6. 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”?
  7. 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