Commit 3b9700b1 authored by Kourser's avatar Kourser
Browse files

chore(android): squelette du portage et plan

android/ accueille une app Kotlin + Compose (Gradle, Kotlin DSL) et un
module :core en Kotlin pur qui porte déjà les formats partagés avec l'app
Apple — positions, livres audio, identifiants, langues — testés sur les
mêmes cas que le code Swift. PORTAGE.md fait la correspondance des briques
(Readium Kotlin, Media3, ML Kit, Android Auto…) et fixe les formats de
fichiers communs. Pas encore compilé : aucun JDK ni SDK Android sur le
poste. .gitignore couvre les fichiers d'Android Studio.

Co-Authored-By: default avatarClaude Opus 5.5 <noreply@anthropic.com>
parent b3680d5f
Loading
Loading
Loading
Loading

android/PORTAGE.md

0 → 100644
+89 −0
Changes for android/PORTAGE.md: 89 added lines, 0 removed lines.
Original line number Diff line number Diff line
# Portage Android — Podbook

> **Plan de portage.** Ce document prépare le portage : ce qui se transpose tel quel, ce qui change d'outil, et les formats que les deux applications doivent partager pour qu'un livre commencé sur iPhone se reprenne sur Android. Le squelette du projet est à côté, voir [README.md](README.md).

## Principe

Une application Android **native**, en Kotlin et Jetpack Compose, et non une couche partagée. Le cœur de Podbook est fait d'intégrations système — lecteur EPUB, voix, traduction sur l'appareil, lecture en arrière-plan, voiture — qui ont toutes leur équivalent natif sur Android et aucun équivalent commun. Ce qui se partage, ce sont **les formats**, **les textes traduits** et **les tests de comportement**, pas le code.

Le dépôt reste unique : `Packages/Core` pour Apple, `android/` pour Android, `localization/` et `docs/` pour les deux.

## Correspondance des briques

| Podbook Apple | Rôle | Android |
|---|---|---|
| `CalibreKit` (URLSession) | Client `calibre-server` : catalogue, conversion, téléchargement, positions, recherche | Module `:calibre`, Kotlin pur, OkHttp + kotlinx.serialization. L'authentification Digest est à réécrire (OkHttp n'a que Basic) ; les tests de `DigestAuthenticationTests` donnent les vecteurs. |
| Readium Swift Toolkit 3.11 | Lecteur EPUB, extraction du texte et des locators | [Readium Kotlin Toolkit](https://github.com/readium/kotlin-toolkit), même projet, **même format de `Locator`** : les positions EPUB passent d'une plateforme à l'autre sans conversion. |
| PDFKit | Lecteur PDF, annotations | Readium (adaptateur PDFium) ou `PdfRenderer` ; l'annotation PDF est le point le plus coûteux, à garder pour la fin. |
| `AVSpeechSynthesizer` (`SystemNarrator`) | Narration voix système | `android.speech.tts.TextToSpeech`, une phrase par `utterance id` pour garder la position à la phrase. |
| `AVPlayer` (`AudioFileNarrator`) | Livres audio | Media3 ExoPlayer, une `MediaItem` par chapitre. |
| `MPNowPlayingInfoCenter`, `MPRemoteCommandCenter` | Écran verrouillé, boutons du volant | Media3 `MediaSessionService` : notification, écran verrouillé, Bluetooth et volant en une seule brique. |
| Mode voiture plein écran | Trois cibles, file qui s'enchaîne | **Android Auto** en application média (`MediaLibraryService`) : contrairement à CarPlay, aucune autorisation spéciale n'est demandée pour une app audio. L'écran plein téléphone reste utile hors Android Auto. |
| Framework `Translation` d'Apple | Traduction sur l'appareil, hors-ligne | ML Kit Translation (modèles téléchargés une fois, hors-ligne ensuite). Mêmes langues sauf contrôle : vérifier le grec, le slovène et le croate. |
| `NLLanguageRecognizer` | Langue d'un livre qui ne la déclare pas | ML Kit Language Identification. |
| Siri, App Intents | « Reprends mon livre », « chapitre suivant » | App Actions / Google Assistant, et les commandes média de la `MediaSession`, qui suffisent pour la voiture. |
| Keychain | Mots de passe Calibre, clés d'API | Android Keystore (clé AES) chiffrant un `DataStore`. |
| `UserDefaults` (`AppSettings`) | Réglages | Jetpack DataStore (Preferences), **mêmes clés** (`podbook.driving.language`, …) pour une éventuelle synchronisation. |
| `AVAudioSession` route change (`DrivingRouteMonitor`) | Détecter l'autoradio | `AudioDeviceCallback` sur `AudioManager` (`TYPE_BLUETOOTH_A2DP`, `TYPE_BUS`). |
| Fichiers, « Ouvrir dans » | Import local | Storage Access Framework (`ACTION_OPEN_DOCUMENT`, `ACTION_OPEN_DOCUMENT_TREE` pour un dossier de livre audio) et un filtre d'intention `ACTION_VIEW`. |
| iPhone Duo (pli) | Disposition autour du pli | Jetpack WindowManager, `FoldingFeature` : même logique que `Fold.swift`. |
| LM Studio / Anthropic (`LLMClient`) | Résumés parlés | Même API HTTP, réécrite avec OkHttp ; les prompts de `DigestPrompts.swift` se copient tels quels. |

## Formats partagés

Ce sont les contrats entre les deux applications. Ils ne changent pas sans changer des deux côtés.

### Identifiants de livres

Entiers. **Positifs** pour un livre Calibre (son id Calibre), **négatifs et décroissants** pour un livre importé sur l'appareil. Toutes les données ci-dessous sont indexées par cet id.

### Positions — `Positions/{bookID}-{FORMAT}.json`

```json
{"locator": "…", "progression": 0.42, "updatedAt": 816338146.02}
```

- `FORMAT` en majuscules : `EPUB`, `PDF`, `AUDIOBOOK`, `BOOK` (mode voiture), `DIGEST-…` (résumés).
- `updatedAt` : **secondes depuis le 1ᵉʳ janvier 2001** (encodage par défaut de `JSONEncoder` chez Apple), pas depuis 1970. Android doit ajouter 978 307 200 s pour obtenir un temps Unix.
- `locator` selon le format :
  - EPUB : le `Locator` Readium sérialisé en JSON, identique en Kotlin ;
  - PDF : numéro de page **à partir de 0**, en texte (`"12"`) ;
  - livre audio : `audio:{chapitre}@{secondes}`, chapitre à partir de 0, secondes entières arrondies par pas de 5 (`audio:2@125`).
- La position la plus récente (`updatedAt`) gagne, quel que soit le format.

### Livre audio — dossier `{id}.audiobook/` et `tracks.json`

```json
{"tracks": [{"file": "001.mp3", "title": "Introduction", "duration": 552.3}]}
```

Les chapitres sont copiés sous des noms numérotés (`001.mp3`, `002.mp3`…) dans l'ordre humain des fichiers d'origine (« 2 » avant « 10 », sous-dossiers compris). Titre et auteur viennent des tags (album, artiste de l'album), à défaut du nom de dossier « Auteur - Titre ». Sans `tracks.json`, les fichiers audio du dossier sont lus dans l'ordre de leur nom.

### Bibliothèque locale — `LocalLibrary/catalog.json`

Tableau de `{id, title, authors, format, fileName, byteCount, contentHash, addedOn}` ; `format` vaut `EPUB`, `PDF`, … ou `AUDIOBOOK`. `contentHash` est le SHA-256 du fichier (ou, pour un livre audio, des noms et tailles de ses fichiers) et sert à refuser un double import.

### Cache de traduction

Clé : SHA-256 de `"{moteur}|{langue cible}|{texte source normalisé}"`, moteur `apple.translation` côté Apple. Android utilisera `mlkit.translation` : les traductions ne se mélangent pas entre moteurs, ce qui est voulu.

### Langues

Les 24 langues de `localization/languages.json`, dans cet ordre, avec les mêmes codes (`zh-Hans`, `pt-BR`).

## Textes de l'interface

`localization/app.json` contient les 475 textes dans les 24 langues, indexés par la phrase française. Android demande des identifiants de ressource : la prochaine étape est d'ajouter à `tools/localize_app.py` une sortie `android/app/src/main/res/values-*/strings.xml`, avec un identifiant stable dérivé de la clé française, pour ne rien retraduire. Les pluriels vont dans des `<plurals>` avec les mêmes catégories que les `.stringsdict`.

## Ordre de portage proposé

1. **`:core`** (déjà amorcé : formats partagés et leurs tests), puis **`:calibre`** — client et tests, sans interface : c'est le plus mécanique et il se vérifie contre `scripts/fake-calibre.py`.
2. **Bibliothèque locale et import** (EPUB, PDF, livres audio), formats ci-dessus.
3. **Lecteur EPUB** Readium, positions, traduction au tap avec ML Kit.
4. **Livres audio et narration** dans une `MediaSessionService`.
5. **Mode voiture**, langue d'écoute, puis Android Auto.
6. Résumés parlés, volet bilingue, annotations, PDF.

## Ce qu'il faut sur le poste

Android Studio (JDK 17 fourni), SDK Android 35 ou plus récent. Rien de cela n'est installé sur le Mac de développement au moment de ce document : le squelette `android/` n'a pas encore été compilé.

android/README.md

0 → 100644
+37 −0
Changes for android/README.md: 37 added lines, 0 removed lines.
Original line number Diff line number Diff line
# Podbook pour Android

Squelette du portage Android : Kotlin, Jetpack Compose, Gradle (Kotlin DSL). Le plan, la correspondance des briques et les formats partagés avec l'app Apple sont dans [PORTAGE.md](PORTAGE.md).

> État : squelette **non encore compilé** — il n'y avait ni JDK ni SDK Android sur le poste qui l'a préparé. La première ouverture dans Android Studio génère le wrapper Gradle et peut proposer de mettre à jour les versions de `gradle/libs.versions.toml`.

## Ouvrir le projet

1. Installer Android Studio (il fournit le JDK 17) et le SDK Android 35.
2. *File › Open…* et choisir ce dossier `android/`, pas la racine du dépôt.
3. Si Android Studio ne le fait pas seul, générer le wrapper :

   ```bash
   gradle wrapper --gradle-version 8.10.2
   ```

4. Lancer la configuration `app` sur un émulateur.

## Structure

```
android/
  settings.gradle.kts         modules : :app, :core
  build.gradle.kts            plugins déclarés, appliqués dans les modules
  gradle/libs.versions.toml   toutes les versions, à un seul endroit
  app/                        l'application Compose (eu.cythin.podbook)
  core/                       formats partagés avec l'app Apple, Kotlin pur, avec leurs tests
```

Le module `core` est une bibliothèque JVM sans dépendance Android : ses tests tournent avec `./gradlew :core:test`, sans émulateur, comme `swift test` côté Apple. Il porte déjà les formats communs (positions, livres audio, identifiants, langues), testés sur les mêmes cas que le code Swift. Le client `calibre-server` viendra dans un module `:calibre` du même genre.

## Conventions reprises de l'app Apple

- Identifiant d'application `eu.cythin.podbook`, le même que sur iOS.
- Livres locaux en identifiants négatifs, Calibre en positifs.
- Positions, livres audio et bibliothèque locale aux formats décrits dans le document de portage, pour qu'un livre passe d'un appareil à l'autre.
- Textes de l'interface générés depuis `localization/app.json`, jamais saisis à la main dans `strings.xml`.
+50 −0
Changes for android/app/build.gradle.kts: 50 added lines, 0 removed lines.
Original line number Diff line number Diff line
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
}

android {
    namespace = "eu.cythin.podbook"
    compileSdk = 35

    defaultConfig {
        // Le même identifiant que l'app Apple.
        applicationId = "eu.cythin.podbook"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "0.1.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }

    buildFeatures {
        compose = true
    }
}

dependencies {
    implementation(project(":core"))

    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.activity.compose)
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.compose.material3)
    debugImplementation(libs.androidx.compose.ui.tooling)
}
+20 −0
Changes for android/app/src/main/AndroidManifest.xml: 20 added lines, 0 removed lines.
Original line number Diff line number Diff line
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application
        android:allowBackup="true"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@android:style/Theme.Material.Light.NoActionBar">

        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>
+50 −0
Changes for android/app/src/main/java/eu/cythin/podbook/MainActivity.kt: 50 added lines, 0 removed lines.
Original line number Diff line number Diff line
package eu.cythin.podbook

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import eu.cythin.podbook.core.PodbookLanguages

/** Point d'entrée. La bibliothèque remplacera cet écran d'attente. */
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    Placeholder()
                }
            }
        }
    }
}

@Composable
private fun Placeholder() {
    Column(
        modifier = Modifier.fillMaxSize().padding(24.dp),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text("Podbook", style = MaterialTheme.typography.headlineMedium)
        Text("Portage Android — ${PodbookLanguages.codes.size} langues prévues")
    }
}

@Preview(showBackground = true)
@Composable
private fun PlaceholderPreview() {
    MaterialTheme { Placeholder() }
}
Loading