Mcaster1Studio

Broadcast Automation Software Suite — Project Plan & Status — Last updated: 2026-03-10 (v0.2.0)

Phase Status

Description

Key Deliverables

Status

Foundation — Shell + AudioEngine + VU Meters

Core.lib · Audio.lib · VUMeterModule · dark.qss · MainWindow · Surface paradigm

✓ Complete

Deck Module — Dual player, waveform, crossfader, BPM

DeckModule · DeckAModule · DeckBModule · WaveformView · CrossfaderWidget · DeckPlayer

✓ Complete

Media Library — MySQL/MariaDB, TagLib scanner, drag-to-deck

MediaLibraryModule · DatabaseManager · ScanWorker · LibraryModel · MusicBrainzLookup

✓ Complete

Encoder Module — 7 codecs, 7-state, DSP chain, list-view, reconnect watchdog

EncoderModule · EncoderSlot · AudioRingBuffer · IcyPusher · EncoderSlotWidget · QSplitter modules

✓ Complete

Effects Rack — 19" virtual rack DSP, IEffectUnit ABI, 6 DSP units

EffectsRackModule · RackSlotWidget · IEffectUnit C ABI · EQ31 · Sonic · Comp · AGC · MicPre · Stereo

✓ Complete

Metadata Module — ICY 2.2 full editor, 70+ fields, 8 groups

MetadataModule · Icy22EditorWidget · MetadataPusher (HTTP PUT)

✓ Complete

Playlist / AutoDJ — Clock templates, rotation engine, broadcast log

PlaylistModule · ClockTemplateEditor · AutoDJEngine · PlaylistWidget

✓ Complete

Podcast Surface — Multi-track recorder, WAV export, PTT module

PodcastModule · PTTModule · SPSC ring buffers · 20ms drain timer · WAV export

✓ Complete

Video / TV Surface — Video playlist, QMediaPlayer, RTMP stub

VideoModule · VideoWidget · VideoPlaylist · RTMP output stub

✓ Complete

Monitor Module — Icecast2/Shoutcast/DNAS polling, listener chart

MonitorModule · StatsPoller · ChartWidget (custom QPainter) · 60-sample ring

✓ Complete

UI Refinement — 3 themes, icons, tray, surface ribbon, event log, scheduler, clock, custom surface, drag-drop

ThemeManager · dark/classic/light QSS · SVG icons · SurfaceTray · SurfaceRibbon · SurfaceEventLog · SurfaceScheduler · ClockModule · CustomSurfaceDialog · ModuleDock float/pin

✓ Complete

AppRibbon — Drag-drop ribbon boxes, weather widget, compact VU meter, tab Add Module

AppRibbon · RibbonBox (drag MIME) · WeatherWidget (wttr.in) · VUMeterWidget compact mode · SurfaceTabBar right-click Add Module

✓ Complete

Refinement Pass — Visual polish, persistence, wiring, edge cases

Ribbon box persistence · ON AIR wiring · dock collapse · splitter size save · duplicate module guard · status bar live updates · Effects Rack default units

● In Progress

UI Enhancements — 3D Clock, Weather redesign, Deck history, Smart ▶, Sub-tab module add fix, Save Session, Ribbon polish

ClockWidget QPainter · WeatherWidget 3D + forecast dialog · DeckPanel track history list · Smart play button · Sub-tab “Add Module” wired · Save Session per surface · Ribbon 100px · NowPlaying removed

✓ Complete

Session Persistence v2 — Auto-save, rename-proof restore, sub-tab UX polish

saveAllSessionState() v2 keys · 1.5s debounce auto-save · stable index-based QSettings (rename-proof) · targetPanel→addModule() restore · double-click sub-tab renames · Save/Load removed from sub-tab menus · moduleLayoutChanged() signal · connectSurfaceAutoSave()

✓ Complete

Encoder Module Redesign — 7 codecs, 7-state machine, per-slot DSP, list-view UI, DNAS stats poller

EncoderConfig · EncoderDsp (10-band EQ + AGC) · EncoderListWidget · EncoderConfigDialog (5 tabs) · DnasPoller · EncoderSlot rewrite · EncoderModule rewrite

✓ Complete

UI Polish & Accessibility — Theme audit, DeckWidget polish, 3D SVG icons, SurfaceTray nav fix

Theme QSS audit · PTT mic fix · EncoderModule dark bleed strip · DeckWidget 12px fonts · SVG 3D icons (play/pause/stop/cue/loop/eject) · SurfaceTray tab nav · tooltips everywhere

✓ Complete

Audio Engine + SQLite DB — IDatabase, HTTP streaming, ICY 1.x/2.2, CartWall, Deck Browser Tabs

IDatabase · SqliteManager · StreamReader (FFmpeg+ICY) · DeckPlayer HTTP · CartWallModule · CartPlayer · Deck browser tabs (History/Library/Playlist/Queue)

✓ Complete

Metadata Flow + VU Meters — Rich ICY from both decks, encoder VU panel, deck VU redesign

Dual-deck metadata wiring · IcyMetadata enrichment (genre/year/BPM) · EncoderVuPanel (hi-res) · DeckInlineMeter smooth gradient redesign · Post-gain peak metering fix

✓ Complete

SDK — Public plugin API, DLL discovery, developer docs

ModuleRegistry public API · IModuleHost interface · Dynamic Add Module menus · SampleModule DLL · SampleEffect DLL · Plugin auto-deploy · Developer Guide

✓ Complete

Church Surface — 12 domain-specific modules for live church services

TimerClockModule · GraphicsEngineModule · LyricsCasterModule · ScriptureCasterModule · AnnounceCasterModule · TelePromptModule · MediaCasterModule · StageMonModule · AudioMixModule · TranscribeRecModule · SwitchCasterModule · ServiceRunnerModule · wireChurchModules() cross-wiring

✓ Complete

Podcast Surface — 13 professional podcast production modules

PodMixerModule · PodPTTModule · PodRecorderModule · PodSoundboardModule · PodFXModule · PodEditorModule · PodEncodeModule · PodTranscribeModule · PodShowNotesModule · PodRSSModule · PodPublisherModule · PodAnalyticsModule · PodRemoteModule · 13 SVG icons

✓ Complete

System Health Module — CPU/memory/encoder monitoring + Prometheus metrics

HealthModule · HealthWidget · MetricsServer · health.svg icon

✓ Complete

Database Architecture — 5-backend IDatabase, per-surface DB isolation, live wiring

DatabaseModule · 5 backends (SQLite/MySQL/PostgreSQL/Firebird/MSSQL) · DatabaseFactory registration · SqlDialect multi-backend DDL · DbServerRegistry (QObject + signals) · SurfaceDbContext live createConnection() · IDbAwareModule live injection · PreferencesDialog live push · MainWindow pushDbContextToSurface() · Integration tests (77 pass) · database.svg icon

✓ Complete

Bug Fix — Module containment (floating docks escape canvas bounds)

ModuleDock qBound clamp · SubSurfacePanel float-transition clamp · ResizableWidget edge-resize clamp · Session restore clamp · 6 fix locations

✓ Complete

BF2

Bug Fix — Module dock positions/sizes not persisting across sessions

Column structure save/restore · Remove conflicting YAML override · 3 root causes fixed

✓ Complete

Surface Isolation, Multi-Monitor & Display Management

DbServerRegistry · SurfaceDbContext · Per-surface DB isolation · SurfaceCreationWizard · SurfaceWindow pop-out · MonitorManager · GPU/capture enum · "Send to Monitor" · YAML failover · Extended schema

Planned

Installer + Polish + AuxDeck — NSIS installer, test harnesses, AudioPipe integration

AuxDeckModule (per-deck audio routing) · NSIS installer (user-dir install) · Mcaster1AudioPipe prefs integration · Auto version bump · 6 test harnesses · Getting Started guide · 43 built-in modules

✓ Done

Bug Fix — Module Containment (2026-03-10)

Fixed: Floating module docks escaping sub-surface canvas bounds

Root cause: All move() and setGeometry() calls for floating docks had zero bounds checking, allowing docks to be positioned with negative Y coordinates (above the canvas viewport) where the title bar becomes inaccessible.
Fix 1 — ModuleDock.cpp:308-312: Direct canvas drag now clamps via qBound(0, pos, canvas->size() - dock->size())
Fix 2 — SubSurfacePanel.cpp:127: Initial stagger position for startFloating=true bounded to canvas dimensions
Fix 3 — SubSurfacePanel.cpp:212: Float-transition (onModuleFloatRequested) position clamped after mapFromGlobal()
Fix 4 — SubSurfacePanel.cpp:534-535: applyLayoutSnapshot() restored floating positions bounded
Fix 5 — SubSurfacePanel.cpp:589-590: restoreLayout() from QSettings positions bounded
Fix 6 — ResizableWidget.cpp:67-75: Edge resize clamps all 4 sides: moveLeft(0), moveTop(0), setRight(pw), setBottom(ph)

Bug Fix 2 — Module Dock Layout Persistence (2026-03-10)

Fixed: Module dock positions, sizes, and column groupings not saving/restoring across sessions

Root cause 1 — Floating dock position clamping: All interactively-added modules start as floating docks within the canvas. During restoreLayout(), saved x/y positions were clamped via qBound(0, x, max(0, canvasWidth - w)). But m_canvas->width() is 0 during loadSavedSurfaces() (MainWindow not yet shown), so max(0, 0 - w) = 0 collapsed ALL positions to (0,0).
Root cause 2 — Deferred size timers unreliable: QTimer::singleShot(0/100/500ms) for applying column splitter sizes after first show was timing-dependent and failed for non-visible panels (other tabs in QStackedWidget where splitter width stays 0).
Root cause 3 — Column structure lost: addModule(mod, false) creates one column per module during session restore. saveLayout() now records per-column moduleIds, and restoreLayout() rebuilds correct groupings.
Root cause 4 — YAML override conflict: restoreAllLayouts() ran AFTER QSettings restore, overwriting properly-restored layouts with stale YAML data. Removed.
Fix 1 — No-clamp floating restore: restoreLayout() now calls found->move(x, y) without clamping when canvas has zero dimensions. New clampFloatingDocks() method runs once when the canvas first receives QEvent::Resize with valid dimensions, properly constraining docks to canvas bounds.
Fix 2 — Event-driven size application: Replaced fragile QTimer::singleShot with event filter on m_splitter for QEvent::Resize — calls applyPendingSizes() deterministically when the splitter first gets a non-zero width.
Fix 3 — Column structure rebuild: saveLayout() saves per-column moduleIds; restoreLayout() tears down one-per-module default columns, recreates saved groupings using QMultiMap for duplicate IDs.

Phase K — Surface Isolation, Multi-Monitor & Display Management (Planned)

Planned — Full architectural plan →

Database Server Registry — Multiple named DB servers in System Preferences (SQLite + MySQL + PostgreSQL); UUID-keyed, first-run migration from legacy single-DB settings ✓ Done (Phase DB)
Per-Surface Database Isolation + Live Wiring — Each surface gets its own DB schema/file; SurfaceDbContext injected into DB-aware modules via IDbAwareModule mixin; DbServerRegistry emits change signals; PreferencesDialog pushes live updates; MainWindow injects contexts at module creation + on assignment change; DatabaseWidget refreshes instantly — no restart needed ✓ Done (Phase DB)
Surface Creation Wizard — Multi-step QWizard: name → DB server selection → schema creation → module selection → confirmation
Pop-Out Surface Windows — Right-click tab → "Pop Out Window" → QMainWindow (resize, maximize, minimize, F11 fullscreen, multi-monitor drag); "Dock Back" returns to tab; session-persisted
Monitor & Display Management — MonitorManager detects all monitors (resolution, DPI, GPU, refresh rate) via DXGI; "Send to Monitor" context menu auto-maximizes on target display; hot-plug handling
Video Capture Device Registry — MediaFoundation/DirectShow enumeration of webcams, capture cards, virtual cameras; displayed in Preferences
YAML Failover — Shadow YAML per surface for DB-down redundancy; auto-sync on save; read-only mode with warning banner on DB failure
Shared vs Isolated — Hardware (audio devices, monitors, capture cards) remains system-shared; data (library, playlists, settings, logs) fully isolated per surface

Phase I — Metadata Flow + VU Meters Completed (2026-03-08)

Completed in Phase I:

Dual-deck metadata wiring — Both Deck A and Deck B now emit rich IcyMetadata (artist, title, album, genre, year, BPM) via buildMetaFromDeck() lambda in MainWindow. Previously only Deck A was wired and only sent the filename as StreamTitle.
MetadataModule → EncoderModule connection — MetadataModule::metadataChanged now properly connected to EncoderModule::onMetadataUpdate(), completing the metadata push pipeline to all active encoder slots.
TagLib genre/year enrichment — DeckPlayer::loadFile() now extracts genre and year from TagLib tags (tag->genre().to8Bit(true), tag->year()), exposed via tagGenre() and tagYear() accessors.
Encoder VU panel — New EncoderVuPanel widget: hi-res vertical L/R bars per encoder slot, measuring real PCM peak levels from EncoderSlot::peakL/R() atomics. 20fps refresh, broadcast-standard ballistics (fast attack, slow release), 3-zone coloring (green/amber/red), peak-hold ticks. Diagnostic header: "VU" (green=signal), "VU --" (gray=receiving but silent), "VU OFF" (red=not in audio chain).
Post-gain peak metering fix — DeckPlayer::processBlock() and processStreamBlock() now measure std::abs(sL * finalGain) instead of pre-gain std::abs(sL). VU meters on both decks and encoders now correctly respond to volume fader, crossfader, and mute.
Deck VU meter redesign — DeckInlineMeter completely rewritten: smooth continuous-fill QLinearGradient bars replacing 30-segment chunky LEDs. 30fps refresh, 3D depth with darker-edge gradients, 1px highlight shine, clip indicator at 0dBFS, tighter 36px layout. Matches modern broadcast software aesthetics.
RT-safe fabsf() — All RT audio code uses fabsf() instead of std::abs() to avoid MSVC resolving std::abs(float) to the integer overload.

Phase CH — Church Surface Completed (2026-03-09)

Completed in Phase CH:

12 domain-specific church modules — Each is a per-instance static library (not DLL plugin). All follow the anonymous namespace widget + #include "Module.moc" pattern.
TimerClockModule — Countdown/count-up timers for service segments, configurable presets, visual alerts at time thresholds
GraphicsEngineModule — Central rendering pipeline for all visual overlays (lyrics, scripture, announcements)
LyricsCasterModule — Worship lyrics display with verse/chorus navigation, CCLI song database integration
ScriptureCasterModule — Bible verse display with book/chapter/verse navigation, multiple translations
AnnounceCasterModule — Announcement/bulletin overlay with rich text, scheduling, rotation
TelePromptModule — Scrolling teleprompter for sermon notes, adjustable speed/size/mirroring
MediaCasterModule — Video/image overlay source for backgrounds, loops, media playback
StageMonModule — Confidence monitor showing current lyrics, next slide, timer, notes to worship team
AudioMixModule — Multi-channel church audio mixer with per-channel gain/mute/solo/EQ/aux sends
TranscribeRecModule — Live sermon transcription recorder with PTT integration, SPSC ring buffer
SwitchCasterModule — Production video switcher with Program/Preview bus, Cut/Dissolve/FTB transitions, lower third
ServiceRunnerModule — Service rundown manager with timed segments (Welcome/Worship/Prayer/Scripture/Sermon/etc.), auto-advance, TimerClock integration
Cross-module wiring — wireChurchModules() in MainWindow scans all surfaces via qobject_cast and wires: GraphicsEngine→visual modules, SwitchCaster→all source modules, StageMon→content modules, ServiceRunner→coordination modules
ISurface.h — Church surface defaults expanded from 6 to 17 modules (5 core + 12 church-specific)
12 SVG icons — 3D raised style matching existing transport icons

Phase PD — Podcast Surface Completed (2026-03-10)

Completed in Phase PD:

13 professional podcast production modules — Per-instance factories (no singletons), all self-contained.
PodMixerModule — 6-channel mixer (Host, Guest 1-2, Soundboard, Music, Phone) with gain/volume/pan/mute/solo/EQ/aux per channel, VU bars, master bus
PodPTTModule — Enhanced PTT with Hold/Toggle/AlwaysOn modes, Cough button, Talkback, VAD (voice activity detection), DSP params
PodRecorderModule — Multi-track WAV recorder with show/episode metadata, markers, takes, time display, transport controls, ring buffer recording
PodSoundboardModule — Sound pad grid with banks (Intro/Outro, Sound FX, Music Beds), QMediaPlayer per pad, OneShot/Toggle/Loop modes, JSON serialization
PodFXModule — 7-processor voice effects chain: Noise Gate, Compressor, De-Esser, Parametric EQ, High-Pass Filter, Limiter, LUFS Meter. Bypass per processor, reorderable chain, RT-safe DSP
PodEditorModule — DAW-style waveform editor: timeline with markers, region selection, cut/trim stubs, playback with position indicator, zoom controls, QMediaPlayer playback
PodEncodeModule — Multi-format export (MP3/AAC/OGG/FLAC/Opus), configurable bitrate/samplerate/channels, ID3 metadata form, LUFS normalization target, job queue with progress
PodTranscribeModule — Transcript segment editor (time/speaker/text/confidence), speaker label management, SRT/VTT export, chapter marker generation (Whisper integration v2)
PodShowNotesModule — WYSIWYG rich text editor with bold/italic/link/timestamp toolbar, templates (Standard/Interview/Solo), chapter markers, resource links, guest bios, HTML/Markdown/text export
PodRSSModule — RSS 2.0 + iTunes namespace feed generator, show settings form, episode table with add/edit/remove, feed validation, XML preview, file export
PodPublisherModule — Multi-target publishing: Local Copy (v1), SFTP/FTP/HTTP (v2 stubs), target management, per-target progress bars
PodAnalyticsModule — Episode stats dashboard: downloads, subscribers, growth trend, bar chart visualization, episode data table, CSV export
PodRemoteModule — Remote guest management: up to 4 guests, status indicators (Disconnected/Waiting/Connected/Error), audio level bars, mute/admit controls, join URL generation (WebRTC v2)
ISurface.h — Podcast surface defaults expanded from 4 to 17 modules (4 core + 13 podcast-specific)
13 SVG icons — Each with unique color theme: blue (mixer), amber (PTT), red (recorder), purple (soundboard), cyan (FX), teal (editor), green (encode), indigo (transcribe), yellow (shownotes), orange (RSS), emerald (publisher), violet (analytics), sky (remote)

Phase DB — Database Module Completed (2026-03-10)

Completed in Phase DB:

DatabaseModule (com.mcaster1.database) — New surface-loadable module providing connection status display, table browser, backup/restore operations, and database initialization. Allows per-surface database management directly from the surface UI.
PostgreSQL backend — Added PostgreSQL to DbServerEntry::Backend enum alongside SQLite and MySQL. Full support with backendDisplayName(), defaultPort(), and isNetworked() for all three backends.
Surface Database Assignments — New section in PreferencesDialog > DB Servers page for per-surface server and schema name assignment. Each surface can be independently assigned to a different DB server and schema via surfaceDb/<schema>/serverId and surfaceDb/<schema>/schemaName QSettings keys.
IDatabase extended — Added executeQuery() and tableNames() pure virtual methods to the IDatabase interface, enabling generic SQL execution and schema introspection from any backend.
database.svg icon — 3D violet style cylinder icon (32×32 viewBox, linearGradient + shine + feDropShadow), consistent with the existing 3D raised icon convention.
DbServerDialog + PreferencesDialog updated — Both dialogs now support all 5 backends: port defaults, connection fields, validation, surface DB assignment table.
Firebird backend (FirebirdManager) — Full IDatabase implementation via Firebird C API. XSQLDA/XSQLVAR result binding, DPB for authentication, explicit transaction management, GENERATED BY DEFAULT AS IDENTITY (Firebird 3+), dual-mode connection (embedded .fdb files or network host:port:database). Conditional: #ifdef M1_HAS_FIREBIRD with stubs. Custom cmake/FindFirebird.cmake.
SQL Server backend (MssqlManager) — Full IDatabase implementation via ODBC API. Auto-detects best ODBC driver via SQLDriversW() (Driver 18 → 17 → 13 → Native Client → legacy). Works with all editions: Express, Developer, Standard, Enterprise, Azure SQL, LocalDB. NVARCHAR for Unicode, IDENTITY(1,1), SCOPE_IDENTITY(), INFORMATION_SCHEMA.TABLES. Conditional: #ifdef M1_HAS_MSSQL (always set on WIN32 — uses odbc32.lib from Windows SDK).
SqlDialect expanded — 5 concrete dialect implementations (SQLite, MySQL, PostgreSQL, Firebird, MSSQL) for backend-specific DDL generation: quoting, auto-increment, data types, limit clauses, schema creation.
Integration tests — tests/test_databases.cpp: 77 tests across all 5 backends — driver registration, SQL dialect verification, full CRUD cycles (insert/loadAll/pathExists/update/delete/executeQuery), DatabaseFactory integration. Uses fprintf(stdout) for Windows console output.
Per-surface DB live wiring (2026-03-10) — Complete real-time DB assignment flow:
- DbServerRegistry now inherits QObject — emits serverListChanged(), serverChanged(id), surfaceAssignmentChanged(surfaceName) signals on all CRUD operations
- SurfaceDbContext::createConnection() fully implemented via DatabaseFactory::create() — handles SQLite file paths, networked backends, driver availability checks
- PreferencesDialog emits surfaceDbAssignmentChanged(surfaceName) when server combo or schema name changes — updates push instantly
- MainWindow::pushDbContextToSurface(sw) scans all modules via dynamic_cast<IDbAwareModule*> and calls setSurfaceDbContext()
- DB context injected at: session restore, surface creation, module add, PreferencesDialog live changes, and dialog accept
- DatabaseModule widget refreshes instantly when context changes — no app restart needed

Phase 12 — Installer + Polish + AuxDeck Completed (2026-03-14)

Completed in Phase 12:

AuxDeckModule (com.mcaster1.auxdeck) — Custom auxiliary deck with per-deck audio device routing. Each instance gets an independent custom name, AIR OUT device, CUE OUT device, volume, VU meters, and full transport controls (load/play/pause/stop/CUE). Mcaster1AudioPipe virtual devices appear automatically in device lists. Users can add multiple AUX Decks per surface for dedicated playback channels (jingles, interviews, background music).
Mcaster1AudioPipe integration — New section in Preferences > Audio page shows AudioPipe installation status, path (C:\Users\USERNAME\Mcaster1\Mcaster1AudioPipes\Mcaster1AudioPipe.exe), launch button, and refresh pipe devices button. Virtual audio pipe devices appear in all PortAudio device dropdowns.
Auto version bump — cmake/AutoBuildNumber.cmake increments a persistent BUILD_NUMBER file on each CMake configure. version.h.in now exposes MCASTER1STUDIO_BUILD_NUMBER and MCASTER1STUDIO_VERSION_FULL (e.g. "0.3.0.42").
NSIS installer — installer/installer.nsi (406 lines): installs to C:\Users\USERNAME\Mcaster1\Mcaster1Studio (no admin required), copies all runtime files (Qt DLLs, vcpkg DLLs, themes, plugins), creates Desktop + Start Menu shortcuts + Getting Started link + Uninstaller. installer/build-installer.bat automates the full build-and-package workflow.
Test harnesses — 6 test executables:
- TestDatabases — 77 tests across all 5 database backends
- TestCore — ModuleRegistry, SqlDialect, DbServerEntry, SurfaceConfig
- TestModules — 18 broadcast module construction + identity + widget tests
- TestChurch — 12 church module construction + identity verification
- TestPodcast — 13 podcast module construction + identity verification
- TestAuxDeck — AuxDeckModule CRUD, device routing, state persistence
Getting Started guide — docs/GettingStarted.html (53KB): comprehensive 10-section first-run walkthrough covering surfaces, modules, audio setup, broadcasting, church services, podcasting, and AudioPipe.
3D SVG icon — auxdeck.svg (indigo gradient, AUX text + speaker waves) matching project icon conventions.
Module catalog — 43 built-in modules in ModuleRegistry (was 42).

Golden Path — Per-Surface Thread Pools + CPU Affinity (2026-03-14)

Completed in Golden Path:

ThreadPoolManager — Singleton that creates/destroys per-surface QThreadPool instances, computes thread budget based on QThread::idealThreadCount(), and manages CPU core affinity via SetThreadAffinityMask on Windows.
SurfaceThreadPool — Per-surface pool wrapper with atomic metrics: tasksSubmitted, tasksCompleted, pendingTaskCount, peakQueueDepth. Created in SurfaceWidget constructor, destroyed in destructor.
IThreadPoolAware mixin — Follows IDbAwareModule injection pattern. MainWindow calls pushThreadPoolToSurface() to inject pools via dynamic_cast<IThreadPoolAware*>.
CPU affinity — PortAudio RT callback: core 0. EncoderSlots: round-robin cores 1-3. Surface pools: cores 4+ (OS scheduled). Disabled on < 4 cores.
5 modules converted — PodEncodeModule, PodEditorModule, PodTranscribeModule, TranscribeRecModule, MediaLibraryModule now use m_pool->submitTask() for heavy work with synchronous fallback.
HealthSnapshot extended — QList<PoolHealth> threadPools, totalWorkerThreads, availableCores, affinityEnabled for real-time pool monitoring.
TestThreadPool — 37 integration tests: pool basics, 100-task submission, metrics tracking, pool lifecycle, multi-surface pools, encoder core assignment, thread isolation verification.

Phase E — Session Persistence v2 Completed (2026-03-05)

Completed in Phase E:

v2 stable QSettings format — All session data now uses integer-indexed keys (session/v2/<si>/sub/<pi>/...) that remain valid after master surface tab renames. Replaces the old name-based Surface/<name>/ keys that broke on rename.
Auto-save on every action — A 1.5s debounced QTimer fires saveAllSessionState() after any dock created/destroyed, sub-tab added/removed/renamed/recolored, or master tab renamed. No user action required.
Correct multi-sub-panel restore — During restore, modules are added via targetPanel->addModule(mod) directly rather than sw->addModule(), avoiding the m_stack->currentIndex() race condition where the stack index is set before the new panel is inserted.
Custom name survives rename — Both customName and tabLabel are stored; on restore the tab label is applied so renamed surfaces ("GRR Broadcast" etc.) reload correctly.
Double-click sub-tab chip to rename — SubSurfaceTabChip::mouseDoubleClickEvent now emits renameRequested, triggering the same QInputDialog as the right-click "Rename..." action.
Removed Save/Load Session from sub-tab menus — Both the chip right-click context menu and the ▼ sessions dropdown no longer show Save/Load Session. Save Session lives only on the master surface tab right-click, saving ALL sub-tabs and modules in one operation.
SurfaceWidget::moduleLayoutChanged() — New signal emitted from connectPanel() on dockCreated / dockDestroyed; wired to scheduleAutoSave() by connectSurfaceAutoSave().
AppRibbon final sizing — Height 100px (RibbonBox 92px), NowPlayingWidget removed from default ribbon. Clock compact widget 88px (3-row: time/date/TZ).

Phase F — Encoder Module Redesign Completed (2026-03-06)

Completed in Phase F:

7 codecs — MP3 (LAME), Opus (libopusenc), Vorbis (libvorbis), FLAC (libFLAC), AAC-LC, HE-AAC-v1, HE-AAC-v2 (fdk-aac). Codec headers isolated to .cpp files (no header pollution).
7-state machine — Idle → Starting → Connecting → Streaming → Reconnecting → Sleep → Error. Auto-reconnect watchdog with configurable retries; wake() transitions Sleep → Connecting.
3 input sources — LiveDeckMix (ring buffer from RT onAudioBlock), PortAudio device (Pa_OpenStream in encoder thread), WASAPI loopback (IAudioClient capture).
Per-slot DSP chain — EncoderDsp runs in encoder thread: 10-band biquad EQ (RBJ IIR, 6 presets: flat/broadcast/spoken_word/classic_rock/country/modern_rock), feedforward AGC with hard limiter, PTT duck (50ms linear ramp).
List-view UI — EncoderListWidget: QTableWidget showing all slots with 2s auto-refresh. Status color-coded: green=LIVE, amber=CONNECTING/RECONNECTING, blue=STARTING, red=ERROR, gray=SLEEP/IDLE. Double-click → config dialog.
5-tab config dialog — EncoderConfigDialog: Basic (server/codec/source), DSP (EQ/AGC), ICY 2.2 (DNAS only, 6 groups), Archive (WAV/MP3), Stats (live read-only).
DnasPoller — Background QThread polling /admin/stats XML (Icecast2) or /admin/mcaster1stats (DNAS) every 15s. Deduplication: one TCP fetch per unique host:port, distributed to all mounts. Emits statsUpdated.
Mcaster1DNAS priority — Default server type is DNAS (not Icecast2). ICY 2.2 tab enabled only for DNAS targets.
PTT propagation — EncoderModule::setPttActive(bool) forwards to all slots with pttDuckEnabled=true. Wired from PTTModule::stateChanged in MainWindow.

Phase 11 — SDK & Public Plugin System Completed (2026-03-06)

Completed in Phase 11:

ModuleRegistry public API — ModuleRegistry.h exposes availableModules(), availableEffects(), createPluginModule(), createPluginEffect(). Centralized canonical module list replaces 3 hardcoded kModules arrays in SurfaceTabBar, SubSurfaceTabBar, and CustomSurfaceDialog.
IModuleHost interface — IModuleHost.h defines the host services contract: logging, version queries, audio engine params, plugins directory. Passed to mcaster1_create_module().
Plugin discovery at startup — M1::initModuleRegistry() called in MainWindow constructor before module factory init. Scans plugins/modules/ and plugins/effects/ for DLLs, validates API version, logs results.
Dynamic Add Module menus — All 3 “Add Module” menus (master tab right-click, sub-tab chip right-click, Custom Surface dialog) now call M1::availableModules() which returns built-in modules + discovered plugin modules.
Plugin factory fallback — MainWindow::createModule() first checks built-in factory map, then falls back to M1::createPluginModule() for third-party DLL modules.
SampleModule DLL — Minimal module plugin example. Auto-deployed to plugins/modules/ via CMake post-build.
SampleEffect DLL — Minimal effect plugin example (gain control). Auto-deployed to plugins/effects/ via CMake post-build.
Developer Guide — SDK/docs/DeveloperGuide.md covers plugin types, C ABI exports, IModule/IEffectUnit interfaces, AudioBuffer, IModuleHost, CMake template, RT safety rules, and EventBus communication.
Cart Wall in module catalog — com.mcaster1.cartwall added to built-in module list and PLANNING.html module catalog.

Phase H — Audio Engine + SQLite DB Completed (2026-03-06)

Completed in Phase H (H.1–H.7):

IDatabase abstraction — Pure virtual interface with SQLite (default, zero-config) and MySQL/MariaDB backends. Factory reads QSettings; falls back to SQLite on MySQL failure.
HTTP stream playback — DeckPlayer::loadUrl() via StreamReader (FFmpeg avformat_open_input() with icy=1 + Icy-Version: 2.2 headers, SPSC ring buffer).
CartWallModule — Instant-play audio grid (4×4 default, up to 8×8). CartPlayer (QAudioDecoder → float32 PCM), CartButton (colored grid buttons with play indicator), F1–F12 shortcuts. Integrated into RT audio callback chain after PTT.
Deck browser tabs — QTabWidget replacing standalone history list. 4 tabs: History, Library (QTableWidget), Playlist, Queue. Right-click context menu: Load to Deck A/B, Add to Queue, Edit Tags. Populated from MediaLibraryModule and QueueModule via MainWindow wiring.
14px font sizes — All DeckWidget text bumped to 14px minimum for Enterprise Pro readability.
QT_MEDIA_BACKEND=ffmpeg — Set before QApplication to force FFmpeg backend (WMF can’t decode OGG/Vorbis).

Phase G — UI Polish & Accessibility Completed (2026-03-06)

Completed in Phase G:

Theme system audit — Removed ALL hardcoded dark setStyleSheet() calls from EncoderListWidget.cpp, EncoderConfigDialog.cpp, PTTWidget.cpp. Replaced with setObjectName() + QSS selectors in all three theme files.
Enterprise Pro font rules — Enforced minimum 12px (body), 14px (medium), 16px (large) across all widget stylesheets. Fixed ~18 violations in light.qss and every inline style in DeckWidget.cpp.
PTT mic always-on fix — MouseButtonRelease now sets State::Off (was incorrectly setting State::Armed, making the mic indicator appear permanently on after creating a DJ or Broadcast surface).
SurfaceTray tab navigation fix — Clicking a module button in the surface tray now switches to the correct sub-surface tab (m_subTabBar + m_stack setCurrentIndex) before calling panel->focusDock(). Previously only focused the dock without switching pages.
3D SVG icons — All 6 transport SVGs redesigned to 32×32 viewBox with 3D raised button style: 3-stop linearGradient background (light→saturated→dark), semi-transparent shine overlay on top half, feDropShadow for depth, white icon glyphs with shadow. New eject.svg added for the unload/eject button.
DeckWidget transport buttons — Replaced Unicode glyphs with SVG icons. Buttons enlarged to 40×34px for better click targets.
DeckWidget controls sizing — Hot cue pads: 36×28px. Artwork: 64×64px with rounded corners. BPM nudge: 22×22px. Mute/AIR/CUE routing: 26-34×24px. Header row height: 28px.
Tooltips — Added descriptive tooltips to every interactive element in DeckWidget that was missing one (artwork, deck badge, state label, VOL caption, fader, all routing buttons).
PTT + Encoder QSS sections — Added #PTTSectionLabel, #PTTHintLabel, #PTTKnobLabel, #EncoderLiveLabel rules to all three theme files with theme-appropriate colors.

Phase D — UI Enhancements Completed (2026-03-05)

Completed in Phase D:

3D LED Clock widget — Complete rewrite: custom QPainter panel, amber LED text, 12-hour format, date row, timezone — matches WeatherWidget aesthetic. Compact height 88px for ribbon (3 rows: time/date/TZ).
WeatherWidget 3D redesign — Full dark 3D panel, QPainter-drawn weather icons (7 categories), left-click opens 5-day forecast dialog with per-day icon+hi/lo/condition cards.
Deck track history list — Replaced WaveformView with a QListWidget showing recently-played tracks (newest first, newest in blue). Empty-state placeholder guidance shown until first track loads.
Smart play button (empty deck) — Clicking ▶ on an empty deck shows a context menu: Play Next from Queue, Open Audio File..., Browse Media Library, drag hint. M3U/PLS files routed to Queue module.
Sub-surface "Add Module" fix — SurfaceWidget::addModuleRequested was emitted but never connected to MainWindow. Fixed: now wires the signal → createModule() + addModule(startFloating=true).
Master surface tab "Save Session" — Right-clicking a master surface tab shows "Save Session" which saves all sub-panels, module lists, layouts. Confirmation in status bar.
Queue module in Add Module lists — com.mcaster1.queue + com.mcaster1.clock added to both sub-surface chip and master tab right-click menus.
Removed static clock from sub-tab bar — The compact clock pinned to the right slot of each sub-surface tab bar has been removed.

Phase C — Refinement Backlog

Remaining items for Phase C refinement pass:

AppRibbon persistence — save/restore which RibbonBoxes are open (clock, weather, VU) across sessions via QSettings
ON AIR button wiring — AppRibbon::onAirToggled signal needs to connect to EncoderModule active-slot state; also reflect per-surface ON AIR
Duplicate module guard — tab right-click "Add Module" should check if a singleton module (deck, encoder, library, etc.) is already on the surface before creating a second instance
ModuleDock collapse button — ▼/▶ button in title bar to collapse/expand content area; save state in QSettings
Status bar live updates — now-playing track from deck + active encoder slot count
EffectsRack default units — pre-populate Sonic Maximizer + EQ31 + Compressor on first load (if no saved state)
Ribbon box visual polish — sizing, spacing, grip width, hover transitions
WeatherWidget live test — verify wttr.in JSON parsing end-to-end with real city name
Compact VU rendering — verify bar fill vs. actual audio levels and peak-hold behavior
Drop indicator fine-tuning — AppRibbon drop indicator x-position edge cases
Shared resource awareness — modules like MediaLibrary, PTT, Encoder are singletons shared across all sub-tabs; "already loaded" indicator in Add Module menus

✓ Resolved in Phase E: Sub-surface session save/restore (v2 auto-save + stable keys + rename-proof restore)

✓ Resolved in Phase G: Theme dark-bleed from Encoder/PTT modules; DeckWidget font sizes; PTT mic always-on; SurfaceTray navigation to correct sub-tab

Technology Stack

Component	Choice
Language	C++20 · MSVC v143 · /MP parallel build
UI	Qt 6.8.3 LTS (Widgets + Network + Multimedia + Svg)
Build	CMake 3.28+ · VS2022 generator · vcpkg x64-windows
Audio I/O	PortAudio 19.7 + ASIO SDK (vcpkg portaudio[asio])
Codecs	libopusenc · libvorbis · libFLAC · fdk-aac · LAME (external)
Video	FFmpeg 8.0.1
Database	SQLite3 · MySQL/MariaDB · PostgreSQL · Firebird · SQL Server (ODBC) — 5-backend architecture via DatabaseFactory
Tag Reading	TagLib 2.1.1 (compiled /EHa)
HTTP	Qt6::Network (weather, ICY) · libcurl 8.18 (monitor, metadata push)
Plugin ABI	DLL C ABI factory functions

Qt lock: Always use C:/Qt/6.8.3/msvc2022_64.
Qt 6.9.1 and 6.10.2 MSVC are missing Qt6Config.cmake.

CMake configure:

cmake -B build -G "Visual Studio 17 2022" -A x64 \
  -DCMAKE_TOOLCHAIN_FILE=.../vcpkg/scripts/buildsystems/vcpkg.cmake \
  -DVCPKG_TARGET_TRIPLET=x64-windows \
  -DCMAKE_PREFIX_PATH="C:/Qt/6.8.3/msvc2022_64"

Build: cmake --build build --config Debug
Run: build\bin\Debug\Mcaster1Studio.exe

Surface Paradigm

Module Catalog

ICY Protocol Compliance

Surface	Intent	Default Modules
Alpha	Primary radio broadcast	VU Meter · Deck A+B · Media Library · Encoder · Playlist
Beta	Secondary / backup broadcast	Deck A+B · Encoder · VU Meter
Company	Corporate streaming	Playlist · Encoder · Metadata · Monitor
DJ	Live DJ performance	Deck A+B · Crossfader · Effects Rack · VU Meter
Entertainment	TV / Video automation	Video · Encoder · Playlist
Social	Socialcasting + RTMP	Encoder · Metadata · Monitor
Podcast	Professional podcast production	PTT · Podcast · Effects Rack · Media Library + 13 podcast modules (Mixer · PTT · Recorder · Soundboard · FX · Editor · Encode · Transcribe · ShowNotes · RSS · Publisher · Analytics · Remote)
Church	Church AV + stream + podcast	PTT · Encoder · VU Meter · Video · Media Library + 12 church modules (TimerClock · Graphics · Lyrics · Scripture · Announce · TelePrompt · MediaCaster · StageMon · AudioMix · TranscribeRec · SwitchCaster · ServiceRunner)
Custom	User-defined	Any modules — chosen via Custom Surface dialog

Module	Plugin ID	Phase	Status
VUMeterModule	`com.mcaster1.vumeter`	1	✓ Done
DeckModule (Combined)	`com.mcaster1.deck`	2	✓ Done
DeckAModule	`com.mcaster1.deck.a`	2	✓ Done
DeckBModule	`com.mcaster1.deck.b`	2	✓ Done
MediaLibraryModule	`com.mcaster1.library`	3	✓ Done
EncoderModule	`com.mcaster1.encoder`	4	✓ Done
EffectsRackModule	`com.mcaster1.effects`	5	✓ Done
MetadataModule	`com.mcaster1.metadata`	6	✓ Done
PlaylistModule	`com.mcaster1.playlist`	7	✓ Done
PodcastModule	`com.mcaster1.podcast`	8	✓ Done
PTTModule	`com.mcaster1.ptt`	8	✓ Done
VideoModule	`com.mcaster1.video`	9	✓ Done
MonitorModule	`com.mcaster1.monitor`	10	✓ Done
ClockModule	`com.mcaster1.clock`	A	✓ Done
QueueModule (AutoDJ)	`com.mcaster1.queue`	B	✓ Done
CartWallModule	`com.mcaster1.cartwall`	H	✓ Done
Church Surface Modules
TimerClockModule	`com.mcaster1.church.timerclock`	CH	✓ Done
GraphicsEngineModule	`com.mcaster1.church.graphics`	CH	✓ Done
LyricsCasterModule	`com.mcaster1.church.lyrics`	CH	✓ Done
ScriptureCasterModule	`com.mcaster1.church.scripture`	CH	✓ Done
AnnounceCasterModule	`com.mcaster1.church.announce`	CH	✓ Done
TelePromptModule	`com.mcaster1.church.teleprompt`	CH	✓ Done
MediaCasterModule	`com.mcaster1.church.mediacaster`	CH	✓ Done
StageMonModule	`com.mcaster1.church.stagemon`	CH	✓ Done
AudioMixModule	`com.mcaster1.church.audiomix`	CH	✓ Done
TranscribeRecModule	`com.mcaster1.church.transcriberec`	CH	✓ Done
SwitchCasterModule	`com.mcaster1.church.switchcaster`	CH	✓ Done
ServiceRunnerModule	`com.mcaster1.church.servicerunner`	CH	✓ Done
Podcast Surface Modules
PodMixerModule	`com.mcaster1.podcast.mixer`	PD	✓ Done
PodPTTModule	`com.mcaster1.podcast.ptt`	PD	✓ Done
PodRecorderModule	`com.mcaster1.podcast.recorder`	PD	✓ Done
PodSoundboardModule	`com.mcaster1.podcast.soundboard`	PD	✓ Done
PodFXModule	`com.mcaster1.podcast.fx`	PD	✓ Done
PodEditorModule	`com.mcaster1.podcast.editor`	PD	✓ Done
PodEncodeModule	`com.mcaster1.podcast.encode`	PD	✓ Done
PodTranscribeModule	`com.mcaster1.podcast.transcribe`	PD	✓ Done
PodShowNotesModule	`com.mcaster1.podcast.shownotes`	PD	✓ Done
PodRSSModule	`com.mcaster1.podcast.rss`	PD	✓ Done
PodPublisherModule	`com.mcaster1.podcast.publisher`	PD	✓ Done
PodAnalyticsModule	`com.mcaster1.podcast.analytics`	PD	✓ Done
PodRemoteModule	`com.mcaster1.podcast.remote`	PD	✓ Done
System Modules
HealthModule	`com.mcaster1.health`	HL	✓ Done
DatabaseModule	`com.mcaster1.database`	DB	✓ Done

Non-negotiable rule: ALL encoder targets MUST send ICY 1.x StreamTitle= even when also sending ICY 2.2. Backward compatibility is mandatory.

ICY 2.2 Field Groups

Server	ICY 1.x	ICY 2.2	Method
Icecast2	✓ Required	✗ N/A	HTTP GET `/admin/metadata?mode=updinfo&song=…`
Shoutcast v1/v2	✓ Required	✗ N/A	In-stream at icy-metaint boundaries
Mcaster1DNAS	✓ Required	✓ Required	HTTP PUT + `Icy-Version: 2.2` header

Group	Prefix	Key Fields
1 — Station	`icy2-station-*`	id · name · logo · genre · url · language
2 — Show	`icy2-show-*`	title · host · start · end · next · description
3 — Track	`icy2-track-*`	title · artist · album · year · genre · artwork · bpm · key · isrc · mbid · label
4 — DJ	`icy2-dj-*`	handle · name · bio · avatar · website · email

Group	Prefix	Key Fields
5 — Social	`icy2-social-*`	twitter · instagram · tiktok · youtube · facebook · twitch · linktree · hashtags
6 — Podcast	`icy2-podcast-*`	title · episode · season · feed · guid · duration · chapter
7 — Broadcast	`icy2-broadcast-*`	mode · relay · cdn · lufs · codec · samplerate · channels
8 — Content	`icy2-content-*`	explicit · live · type (radio\|tv\|podcast\|socialcast) · rating

Encoder Architecture (Phase F)

7 Codecs: MP3 (LAME, if found), Opus (libopusenc), Vorbis (libvorbis), FLAC (libFLAC), AAC-LC / HE-AAC-v1 / HE-AAC-v2 (fdk-aac, if found)

7-State Machine: Idle → Starting → Connecting → Streaming → Reconnecting → Sleep → Error
• wake() transitions Sleep → Connecting
• setPttActive(bool) forwards to EncoderDsp for duck attenuation

Input Sources: LiveDeckMix (ring buffer from onAudioBlock), PortAudio device, WASAPI loopback

Per-slot DSP chain (EncoderDsp, runs in encoder thread):
Input Gain → 10-band biquad EQ (RBJ, 6 presets) → Feedforward AGC + hard limiter → PTT duck (50ms ramp)

RT thread → EncoderModule::onAudioBlock() → AudioRingBuffer::write() (lock-free)
→ Encoder thread → EncoderDsp::process() → encodePcm() → IcyPusher::push() → TCP socket

DnasPoller — QThread background, polls /admin/stats XML every 15s, emits statsUpdated signal
EncoderListWidget — QTableWidget with 2s refresh timer, double-click → EncoderConfigDialog (5 tabs)

Rule	Reason
Never `#include <version>` or create file named `VERSION`	Collides with C++20 header on Windows case-insensitive FS
TagLib: `.to8Bit(true)` + `QString::fromStdString()`	Never call `.toWString()` across DLL boundary
TagLib: compile with `/EHa`	SEH exception safety on corrupt files
`onAudioBlock()`: no Qt, no alloc, no mutex wait	Called from PortAudio RT callback — hard latency constraint
`QApplication::setStyle("Fusion")`	Windows11 style ignores QSS; Fusion is required for all theming
ICY 1.x StreamTitle= always sent even with ICY 2.2	Backward compat — all clients need ICY 1.x
`qt_add_executable()` not `add_executable()`	Triggers MOC/RCC/UIC auto-generation
Never use `slots` as variable/member name	Qt macro `#define slots` — use `clockSlots`, `encoderSlots`, etc.
`VUMeterWidget` compact mode via `setCompact(true)`	Same class; switches rendering path + sizeHint; wire EventBus separately for compact instances
RibbonBox drag MIME: `application/x-m1-ribbon-box`	Pointer as hex string; distinct from module dock MIME `application/x-m1-module-dock`

Project	Path	Relation to Studio
Mcaster1DNAS	`../mcaster1dnas/`	ICY 2.2 streaming server — DNAS encoder target
Mcaster1DSPEncoder	`../Mcaster1DSPEncoder/`	Encoder reference (LAME/Opus/AAC/FLAC patterns)
Mcaster1TagStack	`../Mcaster1TagStack/`	MySQL schema reference · ICY 2.2 editor reference
Mcaster1Castit	`../Mcaster1CastIt/`	Stats monitor reference for Phase 10
Mcaster1AudioPipe	`../Mcaster1AudioPipe/`	Virtual audio routing — zero-latency pipe devices for AUX Deck + encoder chaining

Phase Status

Bug Fix — Module Containment (2026-03-10)

Bug Fix 2 — Module Dock Layout Persistence (2026-03-10)

Phase K — Surface Isolation, Multi-Monitor & Display Management (Planned)

Phase I — Metadata Flow + VU Meters Completed (2026-03-08)

Phase CH — Church Surface Completed (2026-03-09)

Phase PD — Podcast Surface Completed (2026-03-10)

Phase DB — Database Module Completed (2026-03-10)

Phase 12 — Installer + Polish + AuxDeck Completed (2026-03-14)

Golden Path — Per-Surface Thread Pools + CPU Affinity (2026-03-14)

Phase E — Session Persistence v2 Completed (2026-03-05)

Phase F — Encoder Module Redesign Completed (2026-03-06)

Phase 11 — SDK & Public Plugin System Completed (2026-03-06)

Phase H — Audio Engine + SQLite DB Completed (2026-03-06)

Phase G — UI Polish & Accessibility Completed (2026-03-06)

Phase D — UI Enhancements Completed (2026-03-05)

Phase C — Refinement Backlog

Technology Stack

Surface Paradigm

Module Catalog

ICY Protocol Compliance

ICY 2.2 Field Groups

Encoder Architecture (Phase F)

Icecast2 SOURCE Handshake

Critical Rules

Ecosystem Siblings