AudioDB Player QT

Přehled

ADB_Player_QT je monolitický Qt přehrávač navržený pro jednotný provoz audio i video dat. Aplikace funguje samostatně, ale je optimalizovaná pro databázový workflow AudioDB/MFilmDB.

• Hybridní režim: audio-only, video-only, kombinovaný režim i provoz bez databází (přímé otevření souboru).
• Databázové workflow: rychlé vyhledávání, filtrace, statistiky, random výběr souborů a playlist management.
• Pokročilé playback UX: frameless video okno, titulky, screenshoty, crossfade/random režimy, close-to-tray.
• Konsolidace verze: tato stránka popisuje kompletní funkční rozsah pouze pro verzi 0.1.2.2.

UI a workflow

Main Player

• Play/Pause, Stop, Previous/Next, seek bar, volume dial, status řádek DB/runtime.
• Playlist okno, Search dialog, Visualizer toggle, settings a context menu workflow.
• Per-user lokalizace (CZ/EN) a persistence UI stavu.

Video Window (frameless)

• Drag-to-move, edge-resize, fullscreen toggle, always-on-top.
• Průhlednost okna (opacity), kontextové menu, subtitle overlay rendering.

Search / Stats / Settings / Playlist

• Search: kombinované výsledky AudioDB + MFilmDB, filtry, async refresh, contextual actions.
• Stats: souhrn DB statistik, extension breakdown, report export/copy.
• Settings: DB paths, playback flags, shortcuts, subtitles, visualizer, tray chování.
• Playlist: add/remove/reorder/shuffle, random generace, M3U import/export.

Formáty a backendy

Playback vrstvy

• Primární: QtMultimedia player.
• Pomocné: ffprobe (metadata/duration), openmpt (tracker), songtowav fallback.
• Windows UX: helper subprocess volání používají no-console parametry.

Subtitles subsystem

Embedded subtitles

• Best-effort práce s Qt subtitle track API.
• Výběr aktivní stopy a persistence volby.

External sidecar subtitles

• Auto-detekce vedle videa nebo v podsložce .
• Ruční výběr kandidátů přes menu.
• Overlay rendering přes samostatný widget nad video plochou.
• Persistence enabled/path/font size/media vztahu.

Playlist / Random / Performance

• Playlist operace: add/remove/move/shuffle, M3U load/save, random generace položek.
• Random doména: source filtr, extension filtry, count/minutes, path matching, crossfade.
• V0.1.2.2: duration probing neblokuje UI thread při refreshi; chybějící data řeší background worker.
• Cíl: plynulý UI provoz i při větších random seznamech.

Visualizer + MIDI

Visualizer

• Standalone controller nezávislý na hlavním player modulu.
• Toggle/Show/Hide + per-user persistence vybraných voleb.
• Podpora always-on-top a loopback fallback režimů.

MIDI

• MIDI playback backend s routing konfigurací.
• MIDI routing dialog umožňuje mode/routing persistenci.
• MIDI workflow je platformně závislé na dostupných výstupních zařízeních.

Klávesové zkratky

Troubleshooting a diagnostika (detailní)

Problém: FFmpeg/ffprobe se nenacházejí

Symptom: Nelze načíst metadata nebo videa selhávají během playbacku.

Příčina: a nejsou dostupné v PATH nebo v lokální instalaci.

Řešení:

1. Nainstalujte ffmpeg: (Windows) nebo (Linux)
2. Zkontrolujte PATH: nebo
3. Zkontrolujte lokální adresář:
4. Spusťte s flag jako fallback (přehrávač se pokusí o alternativní backend)

Problém: Database se nenachází / nesprávná cesta

Symptom: Search dialog je prázdný nebo se zobrazuje "No databases found".

Příčina: AudioDB.sqlite nebo MFilmDB.sqlite nemají za sebou správné cesty.

Řešení:

1. Zkontrolujte dávkový režim:
2. Použijte Settings dialog v grafické rozhraní a nastavte cesty manuálně
3. Zkontrolujte že soubory SQLite skutečně existují:

Problém: Video se neotevírá nebo selhává playback

Symptom: VideoWindow se otevře ale zůstane černě nebo přehrávání neběží.

Příčina: Codec není podporován, Qt backend selhává, nebo file je poškozený.

Řešení:

1. Zkontrolujte stav v loga: nebo console output
2. Ověřte že ffmpeg sám přehraje video:
3. Zkuste s flag (native Qt backend)
4. Zkuste převést na podpořený codec:

Problém: Titulky se neobjevují na videu

Symptom: External subtitle soubor ".srt" vedle videa ale nejsou zobrazeny.

Příčina: SubtitleOverlay se nenačítá, soubor není kompatibilní, nebo je vypnutý.

Řešení:

1. Zkontrolujte že subtitle soubor existuje: `video.mp4` + `video.srt` (nebo .vtt/.ass)
2. Vkládejte Settings a ověřte že `subtitles/enabled=true`
3. Verifikujte subtitle soubor: (měl by zawrat `00:00:00,000 --> 00:00:05,000`)
4. Zkuste na jiné video s subtitle: pokud funguje, původní soubor je poškozený

Problém: MIDI routing se neaplikuje / zvuky nejsou slyšet

Symptom: MIDI Routing Dialog se otevře, nastavím mapování, ale MIDI out není slyšet.

Příčina: MIDI zařízení není dostupné, mapování není persistováno, nebo openmpt není nainstalován.

Řešení:

1. Zkontrolujte dostupná MIDI zařízení:
2. Ověřte že v MidiRoutingDialog je zařízení vybrané (ne prázdné)
3. Nainstalujte openmpt: pro tracker support

Problém: Random playlist neobsahuje soubory / je prázdná

Symptom: Kliknu Random playlist ale dialog se nic nenačítá.

Příčina: DB je prázdná, soubory neexistují na disku, nebo filter nevyhovuje žádným souborům.

Řešení:

1. Zkontrolujte že AudioDB/MFilmDB jsou naplněny:
2. Zkontrolujte že soubory fyzicky existují na disku (ne jen v DB)
3. Ověřte filter parametry v Random dialog (extension, path pattern, count)
4. Zkuste na jiném extension nebo bez filtrů

Problém: Aplikace je pomalá / nezResponsive

Symptom: grafické rozhraní se zamrzne při Search, playlist generaci nebo duration probing.

Příčina: Těžké výpočty běží na main UI threadu, DB je velká, nebo ffprobe je pomalý.

Řešení:

1. Zkontrolujte velikost DB:
2. Omezujte search na podmnožiny (použijte filtry, ne hledání bez parametru)
3. Zavolejte aplikaci s modem pro headless operaci (žádný UI hang)
4. Zvažte reindex DB:

Problém: Visualizer se nezobrazuje / neobsluhuje audio

Symptom: Visualizer toggle je zapnuty, ale okno se neobjevuje nebo je černé.

Příčina: Visualizer backend není iniciován, audio stream není dostupný, nebo widget je mimo obrazovku.

Řešení:

1. Zkontrolujte že audio je přehráváno (volume > 0, play pokračuje)
2. Zkuste toggle: vypNUTE a znovu zapněTE visualizer
3. Ujistěte se že se váš zvuk přehrává skrze správné zařízení (kontrola Volume mixer)

Known limits / best-effort oblasti

1. Některé codec scénáře závisejí na OS + Qt backend implementaci.
2. Embedded subtitle API dostupnost se liší podle Qt verze/backendu.
3. Externí subtitle parser funguje best-effort dle kvality vstupních souborů.
4. Tracker workflows mohou vyžadovat dostupnost openmpt/songtowav.
5. Nestandardní umístění DB může vyžadovat ruční override cest.