TASKS.md

ZynAddSubFX Android Port - TASKS

Vision

Porter ZynAddSubFX en application Android standalone (sans VST), avec UX entièrement refaite en Jetpack Compose. Le support MIDI est differe apres le MVP sans MIDI.

Contraintes / decisions initiales

• Platforme cible: Android standalone
• UI: Jetpack Compose (refonte complete)
• Pas de VST
• Pas de MIDI dans un premier temps
• minSdk=29 (actuel)
• Backend audio cible: Oboe (AAudio prioritaire)
• ABI initiale: arm64-v8a (elargissement plus tard)

Milestones

M0 - Cadrage technique + extraction moteur headless (Step 1)

• Importer le code source upstream ZynAddSubFX dans third_party/zynaddsubfx/ (ou native/upstream/zynaddsubfx/)
• Documenter la version upstream (commit/tag + licence)
• Inventorier les modules:
  • moteur synthese
  • presets/serialization
  • audio desktop backends
  • MIDI desktop
  • UI desktop
  • VST/plugin
  • dependances tierces
• Classer chaque module: KEEP, ADAPT, EXCLUDE (phase initiale)
• Identifier les points de couplage UI/desktop -> moteur
• Definir la cible “headless engine” Android (rendu audio + presets + parametres)
• Rediger docs/porting/m0_inventory.md
• Rediger docs/porting/m0_headless_target.md
• Definir l’arborescence native cible (sans implementer JNI complet)
• Preparer un squelette CMakeLists.txt de plan (draft non branche si besoin)
• Definir les risques + inconnues bloquantes avant M1
• Documenter la strategie upstream pour Android (third_party/zynaddsubfx assume comme fork local vendored + base commit de reference)

M1 - Integration NDK/CMake + JNI minimal

• Ajouter externalNativeBuild dans app/build.gradle.kts
• Ajouter config NDK/ABIs (arm64-v8a)
• Creer app/src/main/cpp/ + CMakeLists.txt
• Compiler une librairie native minimale .so
• Exposer JNI test (nativeGetVersion, nativeInit)
• Charger la lib depuis Kotlin
• Valider appel JNI dans l’app
• Ajouter ABI x86_64 pour support emulateur/dev
• Evaluer support ABI x86 (32-bit) selon besoin reel (legacy/emulateurs)
• Ajouter une probe de compilation upstream Zyn (headers + generation zyn-version.h/zyn-config.h)
• Compiler un premier fichier upstream Zyn dans zynbridge (src/globals.cpp)
• Integrer rtosc C minimal + Misc/Util.cpp + Containers/ScratchString.cpp dans zynbridge
• Integrer rtosc-cpp (lot principal) + src/version.cpp dans zynbridge
• Integrer tlsf + Misc/Allocator.cpp dans zynbridge
• Integrer Misc/MsgParsing.cpp, Schema.cpp, CallbackRepeater.cpp, MemLocker.cpp, WavFile.cpp
• Integrer mxml (vendored) + Misc/XMLwrapper.cpp dans zynbridge
• Compiler Params/Controller.cpp dans zynbridge
• Compiler Misc/Config.cpp dans zynbridge
• Compiler DSP/FFTwrapper.cpp dans zynbridge (via shim fftw3f temporaire pour debloquer l'integration)
• Compiler Effects/*, Part.cpp, Bank.cpp, BankDb.cpp, Recorder.cpp et Master.cpp dans zynbridge (avec stubs Android temporaires pour Nio/PresetExtractor/bankPorts)

M2 - Audio temps reel Android (premier son)

• Integrer Oboe (optionnel pour robustesse/portabilite; non bloquant pour MIDI Android)
• Mettre en place pipeline audio callback natif
• Produire un son test (sinus si moteur Zyn non pret)
• UI Compose minimale: init/start/test/stop
• Ajouter seam natif render(...) + noteOn/noteOff (stub, pret pour Zyn)
• Brancher un backend de rendu zyn-master experimental dans ZynAndroidEngine (fallback sinus conserve)
• Gerer lifecycle audio (pause/resume) (auto-stop/auto-resume de base)
• Valider stabilite start/stop repetee

M3 - Jouabilite sans MIDI

• Brancher noteOn/noteOff reels vers moteur (backend zyn-master experimental)
• Clavier virtuel Compose (mini clavier tactile 1 octave + release)
• Preset de test embarque
• Presets de demo embarques (.xmz assets) + chargement local via Master::loadXML
• Parametre de base: volume master (slider UI -> moteur)
• Ajouter un bouton Panic (reset voix/FX) pour recuperer des notes fantomes / etats bloques
• Parametres de jeu de base (velocity clavier + octave shift)
• Demo jouable tactile stable

M4 - Architecture propre moteur/UI

• Creer facade Kotlin SynthEngine
• Ajouter queue de commandes UI -> audio
• Stabiliser contrat de parametres (id, type, bornes)
• Ajouter logs/diagnostics JNI natifs
• Eviter locks/allocations sur audio thread

M5 - Refonte UX Compose complete

• Definir navigation et ecrans (Library / Synth / Performance / Settings)
• Composants synth (knobs/sliders/enveloppes)
• Gestion etat via ViewModel
• Portrait/paysage + tablette
• Mode clavier plein ecran avec UX audio minimale
• UX de sauvegarde/restauration d’etat

M6 - Presets historiques (compatibilite)

• Inventorier formats historiques supportes upstream
• Porter parsing/serialization necessaires
• Import via SAF (Storage Access Framework)
• Export presets/banks
• Gestion compat/migration + messages d’erreur
• Corpus de tests de presets

M7 - MIDI Android

• Integrer Android MIDI API (priorite USB, puis BLE)
• Mapper note on/off, CC, pitch bend, program change
• UI de configuration MIDI
• Gerer reconnexion peripheriques
• Tests latence / notes bloquees

M8 - Portage fonctionnel avance / parite

• Completer modules synth manquants
• Remplacer le shim fftw3f temporaire par une solution FFT production (FFTW Android buildable ou alternative compatible)
• Tenter integration FFTW3F_NATIVE via third_party/fftw3 et documenter le blocage actuel (vendor incomplet: codelets generes manquants, symboles solvtab_* au link)
• Preparer un switch CMake pour selectionner le backend FFT (shim actuel vs futur backend prod)
• Effets / routings / multi (selon scope)
• Banque/favoris/recherche/tags
• Export audio offline (optionnel)
• Documenter ecarts restants vs desktop

M9 - Performance, QA, release

• Profiling CPU/memoire multi-appareils
• Optimisations (buffers, NEON si utile, allocations)
• Mesurer et reduire la latence "premiere note" apres chargement de preset (ex: Supersaw ~300-400ms observes en debug)
• Tests stress (polyphonie, presets, lifecycle)
• Stabilisation crashes / logs
• CI Android + builds beta/release
• Definir matrice ABI release (ex: arm64-v8a obligatoire, x86_64 dev/emulateur, armeabi-v7a/x86 selon besoin)
• Checklist de publication
• Pour l'alpha experimentale Play, ajouter la mention d'engagement a respecter les regles pour les contenus familiaux si applicable
• Pour l'alpha experimentale Play, exposer les licences et un lien vers le code source correspondant
• Ajouter un ecran About / Licences dans l'app avec notice GPL adaptee Android (copyright, absence de garantie, lien vers licence et code source), au lieu de reprendre tel quel le bloc interactif type show w / show c
• Definir strategie audio release: conserver AAudio direct ou migrer vers Oboe apres profiling/stress tests

Tests transverses (a maintenir)

• Start/stop audio repete sans crash
• Reprise apres pause/resume Android
• JNI robuste aux parametres invalides
• Chargement preset invalide sans crash
• Rotation ecran sans perte d’etat critique
• Bench CPU/polyphonie sur appareils de test
• Mesurer la latence entre noteOn et emission audible apres chargement de preset (first-note warmup), logguer les presets lents
• Verifier compatibilite page size 16 KB pour toutes les libs natives (arm64-v8a, x86_64) avant publication
• Verifier absence de notes fantomes / accumulation d'effets apres changements repetes de presets (tester All Notes Off + Panic)
• Exercer les stress tests manuels debug (note burst / reload preset) et analyser aaudioErrCb, aaudioXruns, recoveries

Definition de Done par etape

• Build reproducible
• Demo manuelle documentee
• Risques / limites connus documentes
• TODOs de l’etape suivante clairement listes

Publication / Licence (GPL)

• Verifier et documenter precisement les licences de tous les composants embarques (third_party/zynaddsubfx, rtosc, mxml, FFT de production, etc.)
• Ajouter une mention explicite de FFTW3 (GPL v2) dans les notices tierces de release, meme si deja transitivement utilise via Zyn
• Ajouter une notice tierce explicite pour Mini-XML (mxml) (Apache 2.0 + exception GPL/LGPL) avec LICENSE + NOTICE
• Ajouter une notice tierce explicite pour rtosc (licence type MIT) dans la doc de distribution
• Ajouter une notice tierce explicite pour tlsf (BSD) dans la doc de distribution
• Produire un fichier unique THIRD_PARTY_NOTICES (ou LICENSES.md) listant composant, licence, source et texte applicable
• Definir la strategie de publication du fork Android (repo public + instructions de build + notices de licence)
• Documenter les etapes GitHub pour publier la "source correspondante complete" (option repo vendored complet recommandee, option patch-only reproductible)
• Documenter le "minimum publiable" pour distribution binaire (source correspondante + patches + scripts/build files + notices)
• Decider explicitement le perimetre proprietaire vs open-source AVANT refonte UX majeure (si GUI proprietaire souhaitee, evaluer une separation technique/licence reelle)
• Ajouter un fichier docs/porting/LICENSE_DISTRIBUTION_NOTES.md (obligations GPL, attribution, offre de source, checklist release)
• Verifier la compatibilite de la strategie retenue avec la distribution Android (APK/AAB) avant publication