369 lines
8.7 KiB
Markdown
369 lines
8.7 KiB
Markdown
# Cheatsheet Debug – Plugin `google_cast`
|
||
|
||
Guida ultra-rapida per capire **subito** dove guardare quando qualcosa non funziona.
|
||
|
||
---
|
||
|
||
# 1. Flusso mentale in 10 secondi
|
||
|
||
```text
|
||
UI Flutter
|
||
↓
|
||
cast_controller.dart
|
||
↓
|
||
google_cast_controller.dart / custom_cast_controller.dart
|
||
↓
|
||
MethodChannel('google_cast')
|
||
↓
|
||
FlutterCastFrameworkPlugin.kt
|
||
↓
|
||
CastMediaClient / CastQueueManager / CastCustomReceiver / SessionHandler
|
||
↓
|
||
TV / Chromecast / Custom Receiver
|
||
```
|
||
|
||
---
|
||
|
||
# 2. Se succede X → apri questi file
|
||
|
||
## Connessione device non parte
|
||
- `lib/widgets/collection/app_bar/cast/cast_icon_button.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/FlutterCastFrameworkPlugin.kt`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastDialogLauncher.kt`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastSessionHandler.kt`
|
||
|
||
---
|
||
|
||
## Il device si connette ma non parte nessun media
|
||
- `lib/widgets/collection/app_bar/cast/cast_bar_inline.dart`
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastQueueManager.kt`
|
||
|
||
---
|
||
|
||
## Google Cast fa `Invalid Request` appena scelgo il device
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`
|
||
|
||
### Controlla subito:
|
||
- polling avviato troppo presto in `onCastReady`
|
||
- sessione connessa ma queue ancora vuota
|
||
|
||
---
|
||
|
||
## `MediaQueue error 2001`
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastQueueManager.kt`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`
|
||
|
||
### Controlla subito:
|
||
- queue non caricata davvero
|
||
- startIndex invalido
|
||
- callback media attiva senza media reale
|
||
|
||
---
|
||
|
||
## Slideshow fa prima e seconda foto poi si ferma
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`
|
||
|
||
### Segnale tipico:
|
||
non arriva più `onQueueIndexChanged`
|
||
|
||
---
|
||
|
||
## In slideshow un video viene saltato dopo 5 secondi
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `lib/widgets/cast/custom_cast_controller.dart`
|
||
|
||
### Regola corretta:
|
||
- foto → timer
|
||
- video → nessun timer, deve finire da solo
|
||
|
||
---
|
||
|
||
## In manuale/fullscreen le foto avanzano da sole
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `lib/widgets/cast/custom_cast_controller.dart`
|
||
|
||
### Regola corretta:
|
||
- foto manuali/fullscreen → ferme finché non premi next/prev
|
||
- video → a fine video vanno al successivo
|
||
|
||
---
|
||
|
||
## `Invalid startIndex: X`
|
||
- `lib/widgets/collection/app_bar/cast/cast_bar_inline.dart`
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `lib/widgets/cast/custom_cast_controller.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastQueueManager.kt`
|
||
|
||
### Controlla subito:
|
||
- `startIndex` più grande di `entries.length - 1`
|
||
- indice vecchio riusato su nuova selezione
|
||
|
||
---
|
||
|
||
## Seek cambia sulla TV ma non sul telefono
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `lib/widgets/viewer/fullscreen_cast_viewer.dart`
|
||
|
||
### Controlla subito:
|
||
- `seekCast()` aggiorna `positionNotifier`
|
||
- `VideoWidget` locale ascolta `positionNotifier` / `isPlayingNotifier`
|
||
|
||
---
|
||
|
||
## Il volume compare ma la barra non si aggiorna
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
- `lib/widgets/collection/app_bar/cast/cast_controls_sheet.dart`
|
||
- `lib/widgets/viewer/fullscreen_cast_viewer.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastMediaClient.kt`
|
||
|
||
### Controlla subito:
|
||
- dopo `setVolume` e `setMute` fai `refreshVolumeStatus()`
|
||
- nello slider separa `onChanged` e `onChangeEnd`
|
||
|
||
---
|
||
|
||
## Scelgo Google ma sembra partire Custom
|
||
- `lib/widgets/collection/app_bar/cast/cast_icon_button.dart`
|
||
- `lib/widgets/cast/cast_controller.dart`
|
||
- `lib/widgets/cast/custom_cast_controller.dart`
|
||
- `lib/widgets/cast/google_cast_controller.dart`
|
||
|
||
### Controlla subito:
|
||
- backend attivo (`_backend`) allineato col backend scelto
|
||
- icona Cast solo connect-only
|
||
- media avviati solo dalla cast bar
|
||
|
||
---
|
||
|
||
## In selection mode la app bar “tocca” anche le foto sotto
|
||
- `lib/widgets/collection/app_bar/collection_app_bar.dart`
|
||
- `lib/widgets/common/identity/aves_app_bar.dart`
|
||
- `lib/widgets/collection/collection_page.dart`
|
||
|
||
### Controlla subito:
|
||
- la barra assorbe i tap?
|
||
- è presente `AInkResponse` o equivalente?
|
||
- `pinned` + altezza header coerenti col body?
|
||
|
||
---
|
||
|
||
## Custom receiver: progress bar duplicate / overlay strani sulla TV
|
||
- `lib/widgets/cast/custom_cast_controller.dart`
|
||
- `plugins/google_cast/android/src/main/kotlin/com/aves/google_cast/cast/CastCustomReceiver.kt`
|
||
- `receiver.html`
|
||
- eventuale JS del receiver
|
||
|
||
### Controlla subito:
|
||
- il DOM viene pulito prima di ridisegnare?
|
||
- stai creando un nuovo overlay a ogni update?
|
||
|
||
---
|
||
|
||
## Volume Custom non cambia davvero il video
|
||
- `lib/widgets/cast/custom_cast_controller.dart`
|
||
- `receiver.html`
|
||
- JS del receiver
|
||
|
||
### Controlla subito:
|
||
- il receiver gestisce davvero `SET_VOLUME`?
|
||
- aggiorna `video.volume`?
|
||
- risponde con `VOLUME_STATUS`?
|
||
|
||
---
|
||
|
||
# 3. Comando → dove passa
|
||
|
||
## `showCastDialog`
|
||
```text
|
||
CastIconButton
|
||
→ cast_controller.dart
|
||
→ google/custom controller
|
||
→ MethodChannel('google_cast')
|
||
→ FlutterCastFrameworkPlugin.kt
|
||
→ CastDialogLauncher.kt
|
||
```
|
||
|
||
## `loadQueue`
|
||
```text
|
||
CastBarInline / slideshow / fullscreen
|
||
→ cast_controller.dart
|
||
→ google_cast_controller.dart
|
||
→ MethodChannel('google_cast')
|
||
→ FlutterCastFrameworkPlugin.kt
|
||
→ CastQueueManager.kt
|
||
```
|
||
|
||
## `play / pause / seekTo`
|
||
```text
|
||
UI controlli
|
||
→ cast_controller.dart
|
||
→ google/custom controller
|
||
→ MethodChannel('google_cast')
|
||
→ FlutterCastFrameworkPlugin.kt
|
||
→ CastMediaClient.kt
|
||
```
|
||
|
||
## `setVolume / setMute`
|
||
```text
|
||
UI volume slider / mute
|
||
→ cast_controller.dart
|
||
→ google/custom controller
|
||
→ MethodChannel('google_cast')
|
||
→ FlutterCastFrameworkPlugin.kt
|
||
→ CastMediaClient.kt (Google)
|
||
oppure
|
||
→ receiver custom via JSON (Custom)
|
||
```
|
||
|
||
---
|
||
|
||
# 4. Evento → da dove torna
|
||
|
||
## `onCastReady`
|
||
```text
|
||
CastSessionHandler.kt
|
||
→ FlutterCastFrameworkPlugin.kt
|
||
→ MethodChannel callback
|
||
→ google_cast_controller.dart / custom controller
|
||
```
|
||
|
||
## `onQueueIndexChanged`
|
||
```text
|
||
RemoteMediaClient.Callback in CastMediaClient.kt
|
||
→ Flutter invokeMethod
|
||
→ google_cast_controller.dart
|
||
```
|
||
|
||
## `onVideoFinished`
|
||
```text
|
||
RemoteMediaClient.Callback in CastMediaClient.kt
|
||
→ Flutter invokeMethod
|
||
→ google_cast_controller.dart
|
||
```
|
||
|
||
## `MEDIA_STATUS` / `VOLUME_STATUS` (Custom)
|
||
```text
|
||
receiver web
|
||
→ messaggio custom
|
||
→ plugin Android
|
||
→ custom_cast_controller.dart
|
||
```
|
||
|
||
---
|
||
|
||
# 5. Google vs Custom: differenza operativa
|
||
|
||
## Google Cast standard
|
||
Usa:
|
||
- queue nativa Cast
|
||
- volume di sessione Cast
|
||
- callback `RemoteMediaClient`
|
||
|
||
### Se qualcosa non va, guarda prima:
|
||
- `google_cast_controller.dart`
|
||
- `CastMediaClient.kt`
|
||
- `CastQueueManager.kt`
|
||
|
||
---
|
||
|
||
## Custom Receiver
|
||
Usa:
|
||
- messaggi JSON custom
|
||
- receiver web / CAF
|
||
- player HTML5 lato TV
|
||
|
||
### Se qualcosa non va, guarda prima:
|
||
- `custom_cast_controller.dart`
|
||
- `CastCustomReceiver.kt`
|
||
- `receiver.html`
|
||
- JS del receiver
|
||
|
||
---
|
||
|
||
# 6. Regole d’oro
|
||
|
||
## Regola 1
|
||
Se la **TV fa la cosa giusta ma il telefono no**:
|
||
👉 problema quasi sempre lato Flutter/controller/viewer.
|
||
|
||
Guarda:
|
||
- `google_cast_controller.dart`
|
||
- `custom_cast_controller.dart`
|
||
- `fullscreen_cast_viewer.dart`
|
||
|
||
---
|
||
|
||
## Regola 2
|
||
Se **Flutter crede di essere corretto ma la TV fa cose strane**:
|
||
👉 problema spesso lato plugin Android o receiver.
|
||
|
||
Guarda:
|
||
- `CastMediaClient.kt`
|
||
- `CastQueueManager.kt`
|
||
- `CastCustomReceiver.kt`
|
||
- receiver JS/HTML
|
||
|
||
---
|
||
|
||
## Regola 3
|
||
Se il problema nasce **subito dopo la connessione device**:
|
||
👉 controlla sempre la distinzione tra:
|
||
- sessione Cast pronta
|
||
- media davvero caricato
|
||
|
||
Guarda:
|
||
- `CastSessionHandler.kt`
|
||
- `google_cast_controller.dart`
|
||
- `CastMediaClient.kt`
|
||
|
||
---
|
||
|
||
## Regola 4
|
||
Se il bug riguarda **selection mode / app bar / tocchi**:
|
||
👉 il plugin Cast probabilmente non c’entra.
|
||
|
||
Guarda:
|
||
- `collection_app_bar.dart`
|
||
- `aves_app_bar.dart`
|
||
- `collection_page.dart`
|
||
|
||
---
|
||
|
||
# 7. Checklist rapidissima prima di impazzire
|
||
|
||
- Hai salvato tutti i file?
|
||
- Hai eliminato eventuali backtick markdown rimasti nel file?
|
||
- Hai fatto `flutter clean` se i simboli sembrano “mancare” senza senso?
|
||
- Il backend attivo è davvero quello giusto?
|
||
- Il problema è Flutter-side, Android-side o receiver-side?
|
||
|
||
---
|
||
|
||
# 8. Formula finale da ricordare
|
||
|
||
## **Flutter decide l’UX → il plugin Android parla con Cast → il receiver riproduce davvero**
|
||
|
||
Quindi ogni bug va classificato subito così:
|
||
|
||
### A. Flutter / UI
|
||
- notifier
|
||
- app bar
|
||
- selection
|
||
- cast bar
|
||
- fullscreen viewer
|
||
|
||
### B. Plugin Android
|
||
- sessione
|
||
- queue
|
||
- callback media
|
||
- volume nativo
|
||
|
||
### C. Receiver
|
||
- volume custom
|
||
- overlay/progress
|
||
- player HTML5
|
||
- messaggi custom
|