Segnali principali

I segnali principali sono gli errori, gli avvisi e gli eventi di telemetria emessi da playroll-cpp.

Ci sono due tipi di destinatari distinti:

• Segnali rivolti al giocatore: errori e avvisi che la UI può mostrare direttamente al giocatore.
• Segnali operativi: eventi di telemetria che tester e ingegneri usano per diagnosticare problemi di qualità, ciclo di vita, upload e ambiente.

Contratto rivolto all'utente

Il contratto rivolto all'utente è RecorderError.

Ogni errore del recorder rivolto all'utente include:

Campo	Significato
reason	Motivo tecnico-umano restituito attraverso il confine HTTP/API.
ui_error.mode	blocking_modal oppure warning.
ui_error.title	Titolo breve rivolto all'utente.
ui_error.message	Spiegazione rivolta all'utente e azione suggerita.
ui_error.code	Codice stabile sul wire, ad esempio WINDOW_NOT_16_9.
ui_error.dismissible	Indica se la UI può chiudere il messaggio.
ui_error.actions	(opzionale) Array di {type, label, payload} per pulsanti di azione che la UI può renderizzare. type ∈ open_url / open_path / open_folder_picker / copy_to_clipboard. Nuovi codici di errore possono fornire un pulsante di recovery senza lavoro UI — la UI ha un handler generico per ciascun type. Omesso dal JSON quando vuoto.
ui_error.extras	(opzionale) Record<string,string> di campi strutturati per templating + slicing nella telemetria (es. nvenc_status_name, action_hint, checked_drive, driver_version_nvidia). Omesso dal JSON quando vuoto.

blocking_modal significa che la registrazione non deve proseguire o è stata interrotta forzatamente. warning significa che la registrazione può continuare, ma l'utente deve essere consapevole di una condizione degradata.

Errori bloccanti all'avvio

Questi errori bloccano la registrazione prima che la cattura inizi.

Codice	Significato	Azione tipica dell'utente	Famiglia di eventi monitorata
ENCODER_UNAVAILABLE	Non è stato rilevato alcun encoder hardware H.264 compatibile.	Aggiornare i driver GPU o usare una GPU NVIDIA/AMD supportata.	capture.v2.start, capture.prestart
ENCODER_INIT_FAILED	L'encoder GPU selezionato non si è inizializzato.	Aggiornare il driver NVIDIA (fix più comune); chiudere altre app di registrazione; riprovare.	capture.v2.start, capture.v2.nvenc.*
UNKNOWN_ENCODER	L'encoder richiesto non è disponibile in questa build.	Selezionare un encoder supportato.	capture.v2.encoder_policy_override
POOL_ALLOC_FAILED	Allocazione del pool di texture GPU fallita.	Chiudere app che usano molto la GPU, riprovare.	capture.v2.start, capture.v2.pool_pressure
EXTRADATA_TIMEOUT	L'encoder si è inizializzato ma non ha prodotto il keyframe/extradata richiesti.	Riavviare, chiudere consumer dell'encoder, riprovare.	capture.v2.start
MUXER_OPEN_FAILED	Il core non ha potuto aprire l'output MP4.	Controllare i permessi della cartella registrazioni e i lock sui file.	capture.v2.muxer_open
AUTH_EXPIRED	Sessione di autenticazione del giocatore scaduta.	Effettuare di nuovo l'accesso.	recording.blocked, upload.auth_rejected
ALREADY_RECORDING	Una sessione è già attiva.	Interrompere prima la registrazione corrente.	recording.blocked
NO_GAME_DETECTED	Nessun gioco/finestra supportato trovato.	Avviare il gioco e portarlo in primo piano.	recording.blocked
WINDOW_NOT_16_9	La risoluzione/aspetto della finestra non è supportata.	Usare una risoluzione/profilo supportato.	capture.prestart, recording.blocked
WINDOW_SPANS_MONITORS	La finestra del gioco attraversa i bordi del display.	Spostare la finestra interamente su un solo monitor.	capture.prestart, window.diagnostic
DISK_INSUFFICIENT_SPACE	Il disco di output è sotto la soglia di avvio.	Liberare spazio sul drive indicato, oppure spostare la cartella registrazioni su un drive con più spazio.	capture.prestart
OUTPUT_PATH_NOT_WRITABLE	La cartella registrazioni non è scrivibile.	Correggere i permessi o spostare il percorso di output.	capture.prestart
SETTINGS_POLICY_VIOLATION	La baseline grafica richiesta non è applicata.	Applicare le impostazioni Playroll.	recording.blocked_settings_policy, settings.apply_failed
SETTINGS_RESTART_REQUIRED	Le impostazioni sono state applicate mentre il gioco era in esecuzione.	Riavviare il gioco.	recording.start_gate_autofix_blocked_for_restart

Arricchimento errori (extras + actions)

Un sottoinsieme degli errori start-time arriva con ui_error.extras strutturati e ui_error.actions pre-costruiti. Questo permette alla UI di renderizzare un messaggio preciso + un pulsante di azione senza fare parsing del testo human-readable, e permette alle dashboard di affettare per root cause esatta senza regex su reason.

Codice	Chiavi extras	actions[].type (quando applicabile)
ENCODER_INIT_FAILED (path NVENC)	encoder_id, nvenc_status_name (es. INVALID_VERSION, OUT_OF_MEMORY), action_hint (update_driver / free_vram / close_other_recorders)	open_url → download driver NVIDIA, quando action_hint=update_driver
DISK_INSUFFICIENT_SPACE	checked_path, checked_drive, free_bytes, free_gb, total_bytes, total_gb, min_required_bytes, min_required_gb, più install_drive quando differisce da checked_drive	open_path → Esplora File sul drive controllato · open_folder_picker → cambia playroll.recordings_path

Quando si aggiunge un nuovo codice di errore con un action_hint, preferire i quattro actions[].type esistenti (open_url, open_path, open_folder_picker, copy_to_clipboard) — la UI li supporta già. Introdurre un nuovo type solo quando nessun primitive è adatto.

Avvisi all'avvio

Queste condizioni possono essere mostrate all'utente, ma la registrazione può proseguire.

Codice	Significato	Impatto utente	Famiglia di eventi monitorata
AUDIO_UNAVAILABLE	La cattura dell'audio di gioco/sistema non è partita.	L'MP4 potrebbe essere registrato senza audio.	capture.v2.aac, capture.v2.aac_encode, capture.v2.aac_poll

Errori di stop forzato a metà sessione

Questi errori si verificano dopo che una sessione è già iniziata. Il core deve interrompere la sessione, preservare quanto possibile ed esporre un errore terminale a UI/cronologia.

Codice	Significato	Stato finale atteso	Famiglia di eventi monitorata
ASPECT_CHANGED_MIDSESSION	Finestra ridimensionata fuori dal profilo supportato.	La sessione si interrompe e potrebbe essere bloccata in base alla validazione.	recording.window_*, window.diagnostic
DISK_FULL_MIDSESSION	Il disco di output è sceso sotto la soglia di sicurezza.	La sessione si interrompe; l'upload può essere bloccato se gli artefatti sono incompleti.	capture.v2.stop, recording.session_ended
WINDOW_LOST	La finestra del gioco è scomparsa, è stata chiusa o è diventata non disponibile.	La sessione si interrompe con errore terminale.	recording.window_lost, recording.window_timeout
SYSTEM_SUSPEND_MIDSESSION	Windows è andato in sospensione o ibernazione durante la registrazione.	La sessione si interrompe con errore terminale.	capture.v2.stop
ENCODER_FAILURE_MIDSESSION	L'encoder ha smesso di produrre output valido.	La sessione si interrompe; il validator decide la possibilità di upload.	capture.v2.nvenc.encode_failed, capture.v2.zero_video_output_watchdog
SETTINGS_CHANGED_MIDSESSION	Le impostazioni di gioco monitorate sono cambiate durante la registrazione.	La sessione si interrompe per proteggere la coerenza della baseline.	recording.stopped_settings_changed, settings.watchdog_runtime_error

Blocchi ambientali all'avvio del sistema

Questi errori impediscono la capacità di registrazione prima che l'utente avvii una sessione.

Codice	Significato	Azione dell'utente
OS_VERSION_UNSUPPORTED	La build di Windows è troppo vecchia.	Aggiornare Windows.
WGC_NOT_SUPPORTED	Windows Graphics Capture non è disponibile.	Correggere policy/SKU del sistema operativo o reinstallare una versione di Windows supportata.
D3D11_UNAVAILABLE	Creazione del dispositivo Direct3D 11 fallita.	Aggiornare i driver GPU e riavviare.
NO_GPU_ENCODER	Nessun encoder NVIDIA/AMD supportato trovato.	Usare hardware supportato o aggiornare i driver.
NVENC_DRIVER_TOO_OLD	Il driver NVIDIA è sotto la versione minima.	Installare un driver NVIDIA più recente.
AMF_DRIVER_TOO_OLD	Il runtime AMD AMF è sotto la versione minima.	Installare un driver AMD Adrenalin più recente.
WASAPI_NO_DEFAULT_DEVICE	Windows non ha alcun dispositivo di output audio predefinito.	Selezionare o collegare un dispositivo di output.
VM_PERF_INSUFFICIENT	Le prestazioni di cattura in VM sono sotto il minimo.	Usare la macchina host o migliorare l'allocazione di GPU/vCPU della VM.

Avvisi ambientali all'avvio del sistema

Questi avvisi dovrebbero essere visibili perché spiegano probabili registrazioni degradate.

Codice	Significato	Rischio
VM_DETECTED	È stato rilevato un hypervisor.	La qualità della cattura dipende dalla configurazione GPU della VM.
LOW_VRAM	La GPU ha poca memoria video dedicata.	Maggior rischio di frame persi sotto carico.
PROCESS_LOOPBACK_UNAVAILABLE	La cattura audio per-processo non è disponibile.	La registrazione potrebbe includere tutto l'audio di sistema.
MULTI_GPU	Più GPU sono attive.	Possibile cattura nera se gioco e recorder usano GPU diverse.

Campi di contesto allo startup

playroll-core emette una famiglia one-shot service.startup_context_* al boot. Questi campi sono stabili e pensati per essere joinati contro eventi di recording / errore per analisi di coorte.

Evento	Campo	Significato
service.startup_context_adapter	driver_version	Versione driver DXGI Windows raw, es. 32.0.15.6094.
service.startup_context_adapter	driver_version_raw	Stesso valore in esadecimale 64-bit.
service.startup_context_adapter	driver_version_nvidia	Forma NVIDIA XXX.YY, es. 560.94. Popolato solo per adapter con vendor_id = 0x10DE.
service.startup_context_flags	probe.has_nvidia_gpu	true quando cuInit + cuDeviceGetCount riescono.
service.startup_context_flags	probe.default_encoder_id	Attualmente nvenc_h264_tex o vuoto.
service.startup_context_flags	policy.encoder	Attualmente sempre nvenc_only (vedi EC-173).
service.startup_context_flags	nvenc_sdk_min_driver_version	Versione minima del branch driver NVIDIA (XXX.YY) supportata dall'NVENC SDK di questa build. Bumpata insieme all'SDK. Confronta con driver_version_nvidia per trovare utenti sotto la soglia.

Join tipico: nvenc_status_name = 'INVALID_VERSION' (da ENCODER_INIT_FAILED.extras) più driver_version_nvidia < nvenc_sdk_min_driver_version (dal contesto di startup) → utenti il cui driver è dimostrabilmente troppo vecchio per questa build.

Segnali di monitoraggio della qualità

Questi segnali sono telemetria operativa. Non vengono necessariamente mostrati all'utente oggi, ma devono alimentare dashboard, alert e futuri avvisi nella UI.

Evento	Livello	Cosa ci dice
capture.v2.fps_profiler.event	WARNING/INFO	La qualità FPS è degradata, è cambiata per motivo/severità oppure è stata ripristinata.
capture.v2.fps_low_detected	WARNING	Rilevati FPS reali sostenuti sotto 50 (soglie EC-346). Solo osservativo da EC-360: one-shot per sessione, la registrazione continua e viene caricata; il fps_breakdown nei metadati porta lo stesso flag.
capture.v2.dead_capture_detected	WARNING	La maggioranza dei frame muxati sono duplicati CFR — la cattura è di fatto morta (segnale synthetic-ratio di EC-348). Solo osservativo da EC-360, one-shot per sessione.
capture.v2.qos	WARNING/INFO	Pressione sulla coda di cattura, drop, escalation e comportamento di recupero.
capture.v2.qos_saturated	WARNING	La coda di cattura è rimasta satura abbastanza a lungo da generare un avviso.
capture.v2.qos_snapshot	INFO	Contatori periodici dei frame visti/accodati/persi.
capture.v2.pool_pressure	INFO	Attese del pool di texture, slot occupati, disponibilità e percentili di pressione.
capture.v2.encode_stage.frame_metrics	INFO	Throughput, latenza, attese di lock e fallimenti di codifica dell'encode.
capture.v2.packet_queue.depth	INFO	Profondità della coda di pacchetti e blocchi in enqueue.
capture.v2.mux_stage.write_metrics	INFO	Latenza di scrittura MP4, I/O su disco e fallimenti di scrittura.
capture.v2.zero_video_output_watchdog	INFO/WARNING/ERROR	Rileva flussi di cattura/encode senza output video muxato.
capture.v2.nvenc.need_more_input	WARNING	L'encoder chiede ripetutamente più input.
capture.v2.nvenc.zero_bitstream	WARNING	L'encoder ha restituito un bitstream vuoto.
capture.v2.nvenc.encode_failed	ERROR	Chiamata di encode NVENC fallita.
capture.v2.nvenc.lock_failed	ERROR	Lock del bitstream dell'encoder fallito.
capture.v2.mux_stage.write_failed	ERROR	Lo stage di mux non è riuscito a scrivere i dati del pacchetto.

Motivi del profiler FPS

capture.v2.fps_profiler.event usa questi motivi:

Motivo	Significato	Responsabile probabile
low_source_fps	Il lato cattura/sorgente non produce frame abbastanza velocemente.	Performance di cattura/finestra/gioco.
capture_pool_pressure	Saturazione del pool di texture o drop di slot del pool.	Dimensionamento del pool di texture GPU o backpressure a valle.
encode_backpressure	Latenza di encode o attese di lock NVENC sopra il budget.	Contesa di encoder/GPU/driver.
mux_backpressure	Coda di pacchetti, mux o I/O su disco stanno rallentando l'output.	Pipeline di disco o mux.
low_muxed_fps	FPS muxati bassi senza una causa più specifica rilevata.	Richiede indagine incrociata sui segnali.

Soglie di severità per un target di 60 FPS:

Severità	Soglia corrente
good	FPS muxati della finestra almeno 58 e drop ratio inferiore al 5%.
degraded	FPS muxati della finestra inferiori a 58 o drop ratio almeno 5%.
severe	FPS muxati della finestra inferiori a 49,8 o drop ratio almeno 15%.
critical	FPS muxati della finestra inferiori a 45 o drop ratio almeno 30%.

Il profiler ignora i primi 10 secondi come warmup. Gli avvisi di degradazione richiedono due finestre negative; gli avvisi severi e critici possono scattare dopo una sola finestra negativa. Il recupero richiede tre finestre buone consecutive.

Segnali di validazione e idoneità all'upload

La validazione determina se una sessione conclusa può essere caricata.

Evento	Livello	Cosa ci dice
recording.validation	INFO/WARNING	Risultato della validazione finale degli artefatti e diagnostica.
recording.session_ended	INFO/WARNING	Esito della notifica terminale di sessione.
sqlite.session_end	INFO	Lo stato terminale locale della sessione è stato persistito.
sqlite.file_status	INFO	Lo stato di upload dell'artefatto locale è cambiato.
sqlite.sidecars_failed	INFO	I sidecar CSV/JSON sono stati marcati come falliti perché l'MP4 non era caricabile.

I motivi attuali di blocco in validazione includono:

Motivo	Significato
mp4_missing	Il percorso MP4 è mancante o non è possibile fare stat.
mp4_too_small	L'MP4 esiste ma è sotto la dimensione minima del file.
mp4_no_frames	Cattura/metadati indicano nessun frame video.
mp4_duration_unreadable	Impossibile leggere la durata dell'MP4.
mp4_too_short	La durata dell'MP4 è sotto la soglia minima di sessione.
csv_missing	Il percorso CSV è mancante.
csv_parse_error	Il CSV non si apre, ha un header inatteso, righe non valide, timestamp non validi o JSON di evento non valido.
csv_non_monotonic_timestamps	I timestamp CSV sono andati all'indietro.
csv_missing_start	Il CSV non ha un evento di start valido.
csv_missing_end	Il CSV non ha un evento di end valido.
csv_duration_mismatch	La durata CSV è non positiva o non rientra nella tolleranza con MP4/metadati.
json_missing	Il percorso dei metadati JSON è mancante.
json_parse_error	Il JSON non si apre o non si analizza.
json_duration_mismatch	I campi di durata JSON sono non validi o incoerenti.

Da EC-360, mp4_fps_below_threshold non blocca più: un muxed FPS sotto il floor viene aggiunto alla diagnostica di recording.validation (mp4_fps_below_threshold (observe-only)) su un risultato uploadable.

Segnali di monitoraggio dell'upload

La telemetria di upload spiega se un file validato è arrivato a S3 e perché si sono verificati retry o fallimenti.

Evento	Livello	Cosa ci dice
upload.file_start	INFO	Il worker di upload ha iniziato un artefatto.
upload.file_done	INFO	Il worker di upload ha completato la transizione di stato locale.
upload.s3_put_ok	INFO	Upload PUT singolo riuscito.
upload.multipart_start	INFO	Upload multipart avviato.
upload.multipart_ok	INFO	Upload multipart completato.
upload.backoff	INFO	Il worker sta ritentando con backoff.
upload.legacy_audio_blocked	WARNING	Upload OGG legacy bloccato.
upload.sidecar_blocked	WARNING	Sidecar CSV/JSON bloccato perché l'MP4 è mancante o non caricabile.
upload.file_not_ready	WARNING	Il file non è ancora pronto per l'upload.
upload.file_discarded	WARNING	Il file è stato scartato dal flusso di upload.
upload.auth_rejected	WARNING	La richiesta dell'URL di upload è stata rifiutata dall'autenticazione.
upload.user_id_mismatch	WARNING	L'ID utente del file locale non coincide con l'utente autenticato.
upload.presigned_url_failed	ERROR	Il backend non ha restituito un URL presigned utilizzabile.
upload.invalid_presigned_url	ERROR	La forma dell'URL presigned non era valida.
upload.file_missing	ERROR	Il file locale è scomparso prima dell'upload.
upload.file_open_failed	ERROR	Impossibile aprire il file locale.
upload.s3_put_failed	ERROR	PUT S3 fallito.
upload.multipart_*_failed	WARNING/ERROR	Flusso multipart di parte, completamento o abort fallito.
upload.max_retries	ERROR	L'upload ha superato il budget di retry.

Segnali di finestra, pausa e inattività

Questi eventi spiegano perché una sessione è stata messa in pausa, interrotta o è diventata rischiosa durante il gameplay.

Evento	Livello	Significato
recording.window_lost	WARNING	La finestra target è stata distrutta o persa.
recording.window_timeout	WARNING	La finestra target è rimasta non disponibile abbastanza a lungo da innescare il comportamento di timeout.
recording.window_minimized	INFO	La finestra target è stata minimizzata.
recording.window_restored	INFO	La finestra target è tornata.
recording.input_idle_pause_timeout	INFO	Pausa automatica scattata dopo il timeout di inattività dell'input.
idle_warning.reminder_fired	INFO	È stato emesso un promemoria di avviso di inattività mentre era in pausa.

Segnali di applicazione delle impostazioni

L'applicazione delle impostazioni protegge la baseline della registrazione.

Evento	Livello	Significato
recording.blocked_settings_policy	WARNING	L'avvio della registrazione è stato bloccato dalla policy delle impostazioni di gioco.
recording.start_gate_autofix_blocked_for_restart	WARNING	Il core ha applicato le impostazioni ma è necessario il riavvio del gioco.
recording.start_gate_autofix_unfixable	WARNING	Il core non è riuscito a correggere automaticamente le impostazioni.
settings.apply_failed	WARNING	L'applicazione delle impostazioni di gioco richieste è fallita.
settings.restore_failed	WARNING	Il ripristino delle impostazioni originali del gioco è fallito.
settings.watchdog_runtime_error	WARNING	Il watchdog delle impostazioni a runtime ha incontrato un errore di monitoraggio.
recording.stopped_settings_changed	INFO	La registrazione è stata interrotta perché le impostazioni sono cambiate a metà sessione.

Flusso pratico di supporto

Per una sessione fallita o sospetta, ispezionare i segnali in questo ordine:

1. Codice RecorderError mostrato al giocatore, se presente.
2. recording.session_ended e stato finale locale della sessione.
3. Motivo di blocco di recording.validation e diagnostica.
4. capture.v2.fps_profiler.event e snapshot QoS nello stesso intervallo di tempo.
5. capture.v2.zero_video_output_watchdog, eventi NVENC, mux e I/O su disco.
6. Eventi di upload e sqlite.file_status locale.
7. Eventi di watchdog impostazioni e finestra se il giocatore segnala minimizzazione, chiusura del gioco, pausa automatica o cambi di impostazioni.

Manutenzione della documentazione

Quando il core aggiunge un nuovo RecorderError, un motivo di blocco in validazione o un evento operativo che impatta supporto/debugging, aggiornare questa pagina nella stessa modifica.