Release Notes - Callers Caddy

Versioning: 0.XX = Prototype phase (XX = Prototype number).
From the official launch onwards, on 2.0 changed.
Versions 1.xx remain open for the old version.

0.66 — Bug fixes (TIC-0015, TIC-0017, TIC-0018) (2026-04-30)

Bug fixes

TIC-0015 Lyrics zoom level is now correctly restored on app startup — zoom value and auto-size state are stored in the INI file and applied immediately on the next startup.
TIC-0017 The Loop Count dialog in Planner now also finds songs in music folders, slots 2–4 — Function show_loop_count_dialog now uses find_song_file() instead of just slot 1
TIC-0018 Rule action „Load Layout“: The dropdown now shows all saved layouts from the skins/-Folder - layout_names_provider connected, TODO-Stub replaced

0.65 — Stats Dock (BL-019) (2026-04-29)

New Dock: Statistics

New dockable, lazy-loaded "Statistics" window in the View menu (tabbed with Reports)
filter (above): Location (All or individual), Type (Both / Pattern / Singing), Time period (All time / 5 years / 1 year / 3 months / 1 month)
Three columns (scrollable, all songs without limit):
TOP — all played songs, most played first, with number of plays
FLOP — all songs played, least played first, with number of plays
Never played — all songs without play in the current filters, alphabetically
Double-click Clicking on a song jumps directly to the song list.
histogram (Full width): Distribution of all songs by number of plays
Bin 0 is always fixed for "never played", followed by 9 logarithmically distributed bins.
Color gradient from blue (cold = rarely played) to orange-red (hot = often played), regardless of the skin
A tooltip on each bar shows the bin area, number of songs, and up to 5 sample tracks.
Full translations available in German and English.

0.64 — First Steps package, tutorial overhaul, playlist improvements (2026-04-28)

Example project for beginners (first-steps/)

first-steps/folder is included in every new installation
Includes „YRR 049 – Electro Blues.mp3„ by Jon Hansell Nilsson (kindly provided) and the matching lyrics sheet “YRR 049 – Electro Blues.htm”. Yellow Rock Records Offers free pattern music. Definitely worth checking out.
The lyrics sheet humorously addresses the functions of Caller's Caddy.
build.pyStep 3 copied 1_Source/first-steps/ automatically into the app folder

Tutorial: New Songs Tour (completely revised)

Renamed from „Loop Tour“ to „New Songs Tour“
Menu orderNew Songs Tour is now directly after Player Tour (priority 97), Loop Finder directly below it (priority 96), Beat Snap after that.
Step 1 (Import button): Explicit call to action with step-by-step instructions through the three import dialogs — Song type „Both“, Copy, Individual files from first-steps/
Step 2 (Auto-Loop): Loop Finder as a second step instead of manual In/Out setting — manual buttons and Beat Snap removed from the tutorial
Song Data Tutorial Step 4 has been added: "Link lyric sheet" with a reference to first-steps-HTM

Song list: Add song to playlist

→ Playlist button below the song list (next to "Update list" and "→ Note")
Right-click context menu Song list: new entry „Add to playlist“
„The "→ Note" button has been moved from the search bar down into the button bar.

Playlist: Remove songs

✕-Button The arrow keys ▲ ▼ immediately remove the selected song.
Right-click context menu: „Remove from playlist“ at the very top (before separator)
Delete key: QShortcut with WidgetWithChildrenShortcut-Context — works regardless of which child widget has focus

0.63 — LoopFinder Lazy Init, Mapping Export/Import, Sequences Export (2026-04-27)

LoopFinder: Lazy Initialization

LoopFinderWidget It is no longer created at startup, but only when the window is first opened.
Saves ~100ms startup time on weak hardware (Notebook: addDockWidget was 106ms)
Waveform and jump areas are displayed immediately upon opening (no manual "analyze" required for the preview)
Song information will be provided later if a song is already loaded when opening the app.
setFloating and restoreGeometry of the Dock window also via QTimer.singleShot after show() delay

Mapping Export/Import (Sequence Menu)

Export mapping…Saves all call_text_mappings as a JSON file (call_text, entity_id, mapped_by)
Import mapping…: Reads JSON, inserts new entries (INSERT OR IGNOREskips existing
Feedback: "X new mappings imported, Y already exists (skipped)"„
Remapping is automatically triggered for new entries.

Export sequences (JSON)

New menu item Export sequences (JSON)... after the three import points
Exports all sequences in the exact same format as the JSON import expects (id, calls, level, seq_type, difficulty)
The exported file can be directly imported again via "Import sequences (JSON)".

UI detail

Arrow buttons (◀ ▶) and the note button in the Sequence Details window now have a uniform height (40px) — improved accuracy on laptops

Project documentation

CLAUDE.md: setFloating(True) On Windows, it costs ~90ms (once per floating dock context) — it only moves between buckets when you defer it, it doesn't save any overall time.

0.62 — CallMatcher & Sequence UI Improvements (2026-04-27)

Call Mapping: Intelligent Auto-Suggestion (CallMatcher)

Three-stage matching fully integrated sequence_mapper.py Outsourced — no API costs, runs locally in milliseconds
Level 1: Exact comparison after normalization (prefixes/suffixes removed) → Score 1.0
Level 2Bidirectional token overlap (geometric mean of precision × recall) → score up to 0.92
Level 3: difflib.SequenceMatcher as a fallback (only if token score ≥ 0.30) → score up to 0.85
Color coding the call text lines in the mapping dialog:
🟢 Green (Score ≥ 0.85): safe proposal
🟡 Yellow (Score 0.50–0.84): uncertain proposal, manual review recommended
🔴 Red (Score < 0.50): no usable suggestion
Green also applies to already mapped entries
Old _normalize_call_text/_norm_index-System in main.py through CallMatcher-Import replaces

Sequence table: UX improvements

Level, Type and Difficulty columns hidden (setColumnHidden) — Sequence fills the full table width
Type filter dropdown starts with „Singer (Corner progression)“ as the default value (most common type)
Bugfix: ResizeToContent In the Type column, the Sequence column shrank if many rows had the same long type.

Performance logging

New measuring points: SequencesWidget and SequenceViewWidget separately measured
New measuring point: _build_menu (was previously in song_list.refresh hidden)
New measuring point: _init_sequences internally divided (load_sequences + sequence_view prefill)
Bugfix: LoopFinder split incorrectly displayed notes time as well (_td10 → _td10b)

0.61 — Sequence Import & Call Mapping (2026-04-26)

Sequence table extended

New columns type and difficulty in the sequences-Table (migration idempotent)
insert_sequence() now seq_type and difficulty in contrast to
New database methods: get_sequence_type_values(), get_sequence_difficulty_values()

Sequence UI extended

Table: from 3 to 4 columns — sequence (Stretch, instantly visible), Level, Type, Difficult
Second filter row with type- and difficulty-Dropdown
All filters (Contains, Limit, Type, Difficulty) are consistently applied across tables, navigation, and shortcodes.

New import formats in the "Sequences" menu„

JSON import (import_from_json): loads one or more JSON files, appends sequences to
CSDS Import (import_from_csdsVic Ceder's invites you to visit .in/.csds-Export format; parse #EASY#/#REC=/#SEQTYPE=-Metadata and cleaned text-Markup automatically
Deduplication via Ceder record ID during multiple imports
The last import directory is saved in the settings.

Call mapping dialog

New menu item „Call mapping…“ in the sequence menu
Table of all unmapped call texts, sorted by frequency (Most frequent first — one entry can heal many sequences at once)
Right column: editable ComboBox with Contains autocomplete — only opens on click (delegate, no pre-rendering)
Lazy Loading: only 20 lines initially, more appear when scrolling to the end
Yellow highlighting for texts without auto-suggestions
Car suggestion Through normalized text comparison: Prefixes (Heads/Sides/Centers/Boys/Girls…) and suffixes (numbers, fractions, parentheses) are removed.
Special option „→ Split at a comma“: Calls like ""Flutter Wheel, Sweep 1/4"" are split directly within the sequences — subsequent fields automatically shift to the right.
Special entry „"Filler Words"“ (TO=0.001) for filling prophroses that do not have a true level — prevents zero in the level calculation without distorting the result.
After saving, automatically recompute_sequence_max_to() initiated

0.60 — F13–F24 Key Triggers (2026-04-25)

Enhanced F-key support

F13–F24 are now fully-fledged rule triggers — they appear in the rule editor's trigger dropdown menu.
The capture dialog correctly recognizes F13–F24 when pressed and displays them as „F13” etc.
Interception via the app-wide event filter (more reliable than QKeySequence strings, which Qt does not parse for F13+)
Useful for USB remote controls and macro pads that send extended F-key commands.

0.59 — Shortcodes in Notes & Rule Editor Groups (2026-04-24)

Shortcodes in Notes (BL-093)

Shortcode syntax in notes: [load_song "Title"] invites a song; [sequence_view id=42] / [sequence_view contains="Swing Thru" limit="MS"] opens the sequence view with optional filter
Shortcodes are triggered when manual check a note as well as via notes_tick_top-Rule
New module shortcode_parser.py with robust regex parser (positional and named parameters, integer recognition)
→ Note Button In song list, playlist, sequence overview and sequence detail: inserts the current entry as a shortcode into the notes list.
→ Filter Button In sequence overview: adds the active Contains/Limit filters as [sequence_view]-shortcode one
Right-click menu (Context menu) in song list, playlist and sequence table: "Add to notes"„
Warning if no location is selected and a note is to be inserted.
The song title is copied into the shortcode without display suffixes (type, label, quality).

Rule Editor: Actions grouped

The 43 rule actions are now in 10 categories structured: Transport · Audio · Layout & Docks · Lyrics & Scroll · Sequence View · Notes · Workflow · Photo · Genre · Info & Warnings
Non-selectable group headers in the action dropdown for better clarity
The sequence of actions within the groups is logically sorted.
Existing rules remain fully compatible — only the display changes.

0.58 — Sequence Detail as a real dock (2026-04-24)

Sequence Detail as QDockWidget (BL-092)

dock_sequence_view is now a fully functional dock widget — no longer a temporary popup dialog
Can be treated like any other dock: dock_open, dock_close, dock_fullsize, dock_focus, dual_view, Layout-Save/Restore
Clicking on a line in the sequence overview updates the details dock and brings it to the foreground.
In the rule editor under the short name sequence_view available (e.g. dual_view with dock_left=sequences + dock_right=sequence_view)
sequenceview_maximize Opens the Dock as a floating 90 % window — no more conflict with Dual View
Navigation (◀/▶, keyboard ← →) remains active; sequenceview_prev/sequenceview_next-Rule actions directly control the dock
All rule action names are consistently in English: sequenceview_* (instead of sequenceview_*)
Filter SyncIf the user changes the Contains or Limit filter in the sequence overview, the detail dock automatically jumps to the first sequence of the new results list (only if the dock is visible).
Startup pre-fill: When the app starts, the details dock is immediately filled with sequence 1 — no empty window on first opening.

0.57 — SequenceView Navigation & Fullscreen (2026-04-24)

SequenceView — Navigation without closing the dialog (BL-089)

‹ / › Buttons In sequence view: scrolls through the currently filtered list
Position indicator „3 / 12” between the buttons — the caller immediately sees where he is in the list.
Keyboard support: ← / → Arrow keys also navigate (ideal for hands-free operation)
Buttons are automatically deactivated at the beginning and end of the list.
Navigation always refers to the entire filtered list (not just loaded rows).
New DB method get_filtered_sequence_ids() provides all matching IDs for navigation

SequenceView — Auto-Zoom & Free Window Size (BL-090)

Freely enlargeableThe dock can be resized to any size.
font size as it growsThe font size of the calls automatically adjusts to the available window height — the sequence optimally fills the window.
◀ / ▶ Buttons in a uniform size (font-size 16px)
Position label „X / N“ uses the font color of the active theme.

SequenceView — Rule Actions (BL-091)

sequenceview_open: shows the details dock with the current table selection
sequenceview_close: hides the detail dock
sequenceview_prev / sequenceview_next: navigates to the previous/next sequence using a rule/keyboard shortcut
sequenceview_focus: brings the detail dock to the foreground
sequenceview_maximize: makes the detail dock a floating 90% window
Auto-zoom bidirectionalFont size is also adjusted upwards if the initial estimate was too conservative.

0.56 — Dual-View & Song List Quick Navigation (2026-04-23)

Dual-View: two widgets side by side (BL-077)

New rule action dual_viewOpens any two docks as floating windows side by side — together 90 % screen width and height, centered with a 4 px gap
Flexible width ratio: Selection from 50:50, 33:67 or 67:33 directly in the rule editor
New promotion dual_view_closeCloses and docks both dual-view windows.
New promotion dual_view_toggle: One keystroke opens the dual view (layout is automatically saved), a second keystroke restores the original layout exactly — ideal as a keyboard shortcut
All three actions appear with English display names in the rule editor; parameters dock_left, dock_right and split as usual dropdowns
Most common combination: Lyrics on the left + sequences on the right, 50:50

0.55 — Planner loop dialog & double-click fix (2026-04-22)

Planner: Loop dialog with target pattern length pre-set (BL-085)

Loop Count Dialog In the Planner and Playlist widgets, the target pattern length of the active dance program is now automatically used as the default setting (instead of a fixed 7 minutes).
If no dance program is set, the default value of 7 minutes remains.

Playlist widget: Double-click on the Loops column (BL-085)

Double-click on the Loops column The Playlist dock now opens the same loop count dialog as in Planner — the number and time setting can be edited directly.
Reliable triggering via mouseDoubleClickEvent-Override in _PlaylistTable, which has a known Qt 6 timing conflict between DragDrop mode and cellDoubleClicked-signal bypasses

0.54 — Dance Program System & Location Extensions (2026-04-22)

Dance program display in the player (BL-083)

New button btn_program In the player info bar (next to BPM): displays the currently selected dance program abbreviation (e.g. MS, A1 Class)
Quick Selection DialogClicking the button opens a grid of all configured programs as buttons — button width automatically adjusts to the longest text.
14 Default Programs: MS, MS Class, PL, PL Class, A1, A1 Class, A2, A2 Class, C1, C1 Class, C2, C2 Class, C3A, C3A Class — each with configurable target pattern length (standard 7 min)
Administrative dialogue via menu Database → Manage dance programsCreate, rename, adjust order and target pattern length, and delete programs.
New DB table dance_programs; Existing installations will automatically receive the default programs on the next startup (INSERT OR IGNORE)

Location settings: Dance program & temporary tempo (BL-084 + BL-086)

New "Settings" button In the location dialog: opens a settings dialog for the selected location.
Dance program assignment per locationWhen a location is selected, the saved dance program is automatically set in the player.
Temporary pace per locationSpinBox (50–150 %, standard 100 % = no effect). When changing locations, the saved value is automatically transferred to the "Temporary Pace" field — useful for classes and beginner groups with a fixed pace limit.
New DB columns dance_program_id and temp_tempo in the locations-Table (Migration for existing installations)

0.53 — Class Designer: Review & Optimize, Notes Fine-tuning (2026-04-20)

Class Designer — Check & Optimize (new)

„"Check" button In column 3: explicitly triggers overload/underload coloring of the daily headers and distance rule check.
Orange marker for teaches that violate Prereq delay rules (previously red) — clearly separated from the red overload daily header
„"Optimize" buttonIterative Local Search (Best-Improvement Hill Climbing) on the existing plan does not replace generator reassignment, but retrospectively cleans up violations and load imbalances.
Objective function: Violations × 10,000 + Σ(Load − Ø)² — Constraint violations dominate strongly, load variance is fine-tuned below.
Respects manual drag changes in column 3
Hard constraints are checked for each move: pre-delay, follow-up delay, repeat after teach, no duplicate repeats on the same day.
Converges deterministically (max. 200 iterations); typically much faster.
Algorithm classification (RCPSP / Sprint Rebalancing) documented in docs/16_class_designer.md

Class Designer — UX improvements

Effort fields as a row of buttons Instead of a ComboBox: all Fibonacci values (1, 2, 3, 5, 8, 13 or 0–13 for Info) are directly visible as toggle buttons — one click instead of opening a dropdown.
New entries behind selected elementWith „+ Call“ and „+ Info“, the new element is inserted after the currently selected one (instead of at the end) and automatically highlighted — chain insertion works naturally.
Effort filter in column 2: Toggle button row 0 | 1 | 2 | 3 | 5 | 8 | 13 Between the toolbar and the planning table. All are active by default — allowing you to check at a glance whether calls with the same effort are also similarly time-consuming.
n_evenings It is stored in the Col3 widget so that Optimize works with the correct frame even after manual changes.

Notes widget — Display & Editing

Top open note enlarged 4x (BL-079): The most important note is prominently displayed as a large, bold headline — magnification factor configurable in INI (notes/first_note_factor, Default 4.0)
Compact line spacing For long, multi-line texts: The label now renders word breaks itself (instead of using Qt's standard line height) and uses approximately 90 % of the font size as a line break — saving considerable space on the large first line without cutting off the descender.
Word break For very long notes: Text wraps cleanly within the line, line height increases accordingly.
Double-click to edit: Left-clicking on a note line opens an edit dialog with a multi-line text field — styled to match the theme, language follows UI setting (DE/EN), Ctrl+Enter confirmed
Zoom buttons +/− still active — the new rendering logic respects the zoom level
New DB method update_note_text(note_id, text) in song_db

Rule system

New promotion notes_tick_top (BL-080): Checks off the top open note of the active location — useful, for example, for keyboard shortcuts or timer events. If the list is empty, it is silently ignored (no error message).

Internal cleanup

New Helper Widget _ValueButtonRow for exclusive value selection (reusable for further discreet selections)
Helper _insert_after_selected() In Col2 — centralized insertion logic
New QLabel subclass TightLabel with own paintEvent + manual word wrapping for precise line spacing control
New modal dialogue _NoteEditDialog

0.52 — Class Designer (Prototype) & Tracking Fix (2026-04-17)

Class Designer — First Prototype

NoticeThis is the first prototype of the Class Designer — further refinement is definitely needed
More even point distribution per daySwitch to greedy bin filling. Each day is filled up to the target budget (total points / number of days) before the next day is filled.
Repeat constraints are respectedRepetitions of the same figure will still have at least a 1-day interval; pre-delays will remain in place.
Underfilled days avoidedIf a repeater is used because earliestIf the constraint jumps ahead, the day pointer lags behind — subsequent teaches fill in the remaining day instead of leaving it empty.

Loop Finder — Time display under search areas

Playing times under the percentage fields: Under each of the 4 percent fields (Loop-In Start/End, Loop-Out Start/End), the specific playing time of the loaded song is now displayed in the format m:ss displayed (e.g. 0:53This allows the caller to see at a glance where the search area is located within the song.
The display updates live when percentage values are entered and when the waveform handles are dragged.
Uniform line height: Preset combo boxes and load/save buttons now use the same height as the percentage spin boxes.

Bugfix — Playback history

Tracking only during actual playPreviously, the "Last Played" column was updated simply by selecting/loading a file. Now, the timestamp is only set when the play button is actually pressed. The song does not need to play through completely.
The DB entry in play_history That was already correct, only the UI column was ahead.

0.51 — Notes widget improvements (2026-04-15)

Notes widget — redesign & new features

Export folder notes/A new subfolder will be created automatically; this is the default location for loading/saving JSON files.
background colorThe "Done" list now has the same background color as the "Open" list — a consistent appearance.
Export marking: Selection checkbox replaced by _SelectToggle (○ / ✓) — no more Qt-QSS problem with invisible checkmark
Drag Highlight: The dragged row receives a colored background and left border (accent color) during the move.
Select all / Deselect allTwo new buttons All ✓ and All ○ for fast export selection
Zoom controls: − / 100% / + Top right — only changes the font size of the list entries; icons from the active skin
Zoom persistenceZoom setting is stored in INI file (notes/zoom_pct) and restored on the next start
Timestamp for completed items: Completion date will be in the format [DD.MM.YY HH:MM] displayed behind the text
Import orderNotes loaded from JSON are inserted at the top in the correct order.
Done-Toggle: ☐ (open) / ☑ (done) — Pen experiment undone

Loop Active Checkbox — Accessibility

Visible hookAll 4 skin QSS files have been expanded — QCheckBox::indicator:checked now shows a white checkmark (check.svg) on a colored background

Sequence Widget

Zoom persistenceZoom setting is stored in INI file (sequences/zoom_pct) and restored upon startup

performance

Notes dock lazyThe widget is only created on first opening (like Reports, Potential, Photo) — no startup overhead.

0.50 — Freely assignable key triggers (2026-04-09)

Create your own key triggers (BL-064)

New button „+“ in the Rules dialog next to the trigger selection
Clicking opens a mini-dialog: User presses any key — the trigger name is automatically determined.
Supported keys: A-Z, 0-9, F1-F12, Space, Return, Delete, Tab, Escape, Insert, Backspace, Home, End, PageUp, PageDown
After creation, the new trigger immediately appears in the trigger list and can be assigned to a rule.
persistenceNew triggers are automatically restored when the app starts, provided at least one rule is linked to them.
Focus SafetyKey triggers will not fire when a text field or search is active—these always take priority. This will automatically apply to all future triggers.
Dynamic event filter: No longer hardcoded — all registered key_*Triggers are automatically detected and forwarded.

0.49 — Label detection (bidirectional), lyrics co-import (2026-04-08)

Label recognition — bidirectional file naming

Format 1 (Title Label): Ring Of Fire-RYL818.mp3 → Title: „Ring Of Fire“, Label: „RYL818“
Format 2 (Label Title): RYL818-Ring Of Fire.mp3 → Title: „Ring Of Fire“, Label: „RYL818“
With spaces in the label: YRR 043a-Dunderklumpen.mp3 or Dunderklumpen-YRR 043a.mp3
Regular expression pattern: letters + optional space + numbers + optional suffix (a/b/+)
Supported label formats: BVR113, RYL818+, YRR 043a, RBS 1326

Lyrics co-import

When importing MP3s, a lyrics file with the same name (without extension suffix) is automatically searched for.
Source folder (import folder)RTF/HTML/TXT file is converted to lyrics/-folder copied
Lyrics folder: Already exists → will be linked directly
Supported poetry formats: .rtf, .htm, .html, .txt
Log output: [Import] Lyrics linked: upon successful assignment

0.48 — SqView migration, blind import, theme fix (2026-04-08)

SqView Migration (BL-011)

Folder selection: User selects the SqView folder directly via Explorer — sqview.db, MP3/ and text/ are automatically detected
Blind importSongs are fully entered into the database even without existing MP3 files (filename as a placeholder). MP3s can be added later via normal file import—existing entries are automatically activated instead of being skipped as duplicates.
Full song recognitionReads all ~200 songs markext1/2/3 + track-table (not just the ~10 with explicit settings in the music-Tabel)
Recursive MP3 IndexSearches all subfolders (pattern/, singer/, Karaoke/ etc.)
Lyrics matching: 4-stage regex strategy — exact title, label strip (- RBS 1234), Normalization (alphanumeric), Combination
Loop and pitch takeover: Values from the SqView-music-Table will be adopted
Playback history: Out of track-Table with date/time and location assignment
Music folder is optional (blind import also works without it)
MP3 counting in the status display is now recursive.

Enable blind import (file import)

During a normal MP3 import: A database entry already exists for the filename, but the file itself is still missing. music/-Folder → File is copied and the song is activated (instead of being skipped as a duplicate)

Bugfix: Song Data — light background in the default theme

QScrollArea-The viewport and its contents did not receive a dark background (Qt stylesheet inheritance does not extend across viewport boundaries)
Fix in all 4 themes (default, win11, elegant, light)

0.47 — Loop Finder Presets, CrossFade Beat Snap (2026-04-07)

Loop Finder: Parameter Presets (BL-046)

Preset Combo Box Replaces the old reset button: displays all saved presets; "Standard" cannot be overwritten.
Load-Button: Applies the selected preset to search areas, comparison windows, and strategy.
Save-Button: Always active — with „Standard“ an input dialog for a new name appears, with user presets direct overwriting
Presets as JSON files in the folder loop_presets/ — portable and editable
Strategy Combo Box In the analysis row: shows all available selection strategies (currently: „"Best multiple of 64 beats"“), is saved and loaded with the preset; further strategies can be added at any time
Rules action „Auto-Set Best Loop“ now has parameters preset (Dropdown of all saved presets)
Fully loads search areas, comparison windows, and strategy from the selected preset.
Newer preset_choice-Parameter type in rule_widget.py with preset_names_provider

CrossFade in Beat Snap (BL-067)

New toggle button CrossFade between Snap and Prelistening
When active: Pre-listening to the loop jump with the same crossfade as in normal operation.
Automatically deactivated with every load and every waveform change.

Taskbar icon laptop fix

cc-logo.png It is copied to the app root during the build process (previously only available on build machines).

0.46 — Live Volume (BL-070), UI Grid Player (2026-04-07)

Live Volume / Minimum Volume (BL-070)

Newer Live Volume Slider in the player (4th column next to Today's Tempo / Song Tempo / Pitch)
Artifact-free volume change via Windows WASAPI (pycaw) — outside the audio stream, no crackling during fast movements
Reset to 100% on every song change (not persistent)
INI setting audio/min_volume (Default 0.0): The slider cannot be lowered below this value.
The information will be automatically written to the INI file at app startup if it is missing.
Graceful Degradation: without pycaw (no Windows device) the function remains silent, the app continues to run normally.

Rules action: Change live volume

New promotion „Change Live Volume (±)“ with adjustable delta in percentage points (−100 to +100, default −10)
Automatically respects the min_volume-Limit from the INI

UI: Player rows in a uniform 4-square grid

Line „Today’s tempo / song tempo / pitch / live volume“: QGridLayout with columnStretch=1 + QSizePolicy.Ignored → columns of exactly equal width
Line „Location / Planner / Lyrics / Loop active“: also transferred to the 4-column grid, flush with the line above.
Labels with setWordWrap(True) — no text inflates its column

0.45 — Genre system, rules drag&drop, bug fixes (2026-04-06)

Bugfix: Reports and potential Dock crash on first opening

setFloating(True) in the visibilityChanged-Handler triggered a re-entrant signal call → Crash
Fix: Disconnect signal immediately + initialize via QTimer.singleShot(0, ...) reset
Regards _on_reports_visibility and _on_potential_visibility

Genre / Tags (BL-063)

Songs can have multiple genres/tags (Many-to-Many)
65 Default Genres from Square Dance Labels + musicforcallers.com (decades, styles, artists, themes, square dance specific, NEW)
seed_default_genres() is idempotent — it only adds missing genres, existing ones remain intact.
Genre management (Menu Database → „Manage genres…“):
List of all genres with song counter
Create, rename, delete
When deleting with associated songs: Option to "Switch to another genre" or "Simply remove"„
Song recordGenre tags as clickable display + „…“ button opens checkbox dialog
It's possible to create a new genre directly in the dialogue.
Changes are saved immediately.
Import keyword matching: During import, genres are automatically suggested from the filename (e.g., "Christmas" from "Xmas Song.mp3")
Rules actions: „Add Genre to Song“ and „Remove Genre from Song“
Parameters as a dropdown of all available genres (no free text → no duplicates)
Newer genre_choice-Parameter type in rule_widget.py with genre_names_provider

Rules: Reorder actions via drag & drop

Each action row has a [unintelligible element] on the left. ≡-Handle (Cursor ↕)
Dragging moves the row to the new position live.
The sequence of actions is saved immediately.
Bugfix: _on_action_type_changed had an incorrect index after handle insertion (combo was removed instead of Params)

0.44 — Multi-music paths, Import Copy/Keep (2026-04-05)

Multiple music directories (up to 4)

Up to 4 music paths can be configured (Slot 1 = main folder, Slots 2–4 optional)
find_song_file() Searches in sequence slot 1 → 2 → 3 → 4, returns first match.
New dialog „Manage Music Paths“ (Paths menu) with Browse + Clear per slot
Menu text: „Change music directory“ → „Manage music paths“
Migration: Alter INI key paths/music_dir will be automatically after paths/music_dir_1 transmitted
Good for callers with program data on one drive and music files on another.

Import: Copy or leave in place

New intermediate dialog after song type selection: "Copy files?" or "Leave in place"„
Copying: previous behavior — files go into the music/ main directory
Leave as is: Files remain where they are, only a database entry is created.
If you leave it as is: if the source folder is not yet entered as the music path, ask if it should be added as a free slot.
If all 4 slots are occupied: a warning message will appear with a link to the administration dialog.

Single-Instance-Lock more robust (Race Condition on double-click)

Replaces QLocalServer/QLocalSocket with atomic QLockFile
Double-clicking run_test.bat or the EXE file no longer starts a second instance.

Minimum width player and loop dock

Player dock: min. 340px — prevents unleshares from being squashed together
Loop dock: min. 400px — all 4 buttons remain readable side by side.

Performance optimization Startup (−22% on laptop)

Reports Dock: setFloating(True) is no longer set at startup, but only upon first opening (lazy) → -318ms on laptop
Potential Dock: same optimization → -137ms on laptop
Total laptop sms saving: ~526ms (2415ms → 1889ms)
Notice to customersThe app may take a few seconds longer to launch the first time after an update — Windows Defender is scanning the new files. From the second launch onwards, everything is normal.

0.43 — UI minimum heights, song data scroll, first-start voice prompt, Quickwin bundle (2026-04-04)

New Rule Action: Change Song Tempo (persistent)

song_tempo_change supplements the previous tempo_change
tempo_change (renamed to "Change Today's Tempo (±%)"): current pace, not persistent
song_tempo_change ("Change Song Tempo (±%, persistent)"): changes the song tempo and saves the value to the existing auto-save chain in the database.
Parameter: delta as integer percent, Clamp 50-150%

Fault-tolerant import/migration (BL-065)

Manual import: Per-file try/except — corrupt/unreadable files are skipped, session continues.
CC1 migration: shutil.copy2 Each MP3 file is encapsulated, errors are logged, and a report is generated at the end.
SqView migration: same fault resilience
Also player._load_file() Fault-tolerant at the end of the import process — a corrupted last file no longer aborts the summary.

Folder import with subfolders (BL-032)

New intermediate dialog "Import source": Individual files or folders (including subfolders)
When selecting a folder, the system recursively searches for .mp3/.wav/.flac/.ogg/.aiff/.aif files.
Thorsten's long-term feature request fulfilled

Active tab more easily identifiable (BL-060)

QTabBar::tab:selected in all themes with font-weight: bold
Win11: Border changed from 2px to 3px, more explicit widget_bg-Background
Default: additional 2px top border in selection color
Light: Bold adds to it, elegant was already bold

Import note: where the songs end up (BL-062)

After successful import, the song list dock is automatically brought to the foreground.
Import summary includes a new note: "The new songs have been added to the song list."„

TIC-0014: Minimum player height during app resizing

MainWindow.setMinimumSize() increased from (1100, 650) to (1100, 720)
The sum of Player (350) + Loop (240) + Title bars + Menu + Status bar now fits within the minimum height.
The bottom row of buttons (Location, Planner, Lyrics) is no longer cut off when the main window is minimized.

Initial startup voice prompt (BL-058)

On the very first start (no language in INI), a dialog box appears: "Start in English" / "Start in German"„
The language is then stored in the INI file; the dialog only appears once.

UI: Minimum heights against crushing (TIC-0008, TIC-0013)

Player buttons (Play, Pause, Stop, Fade Out, Location, Planner, Lyrics): Minimum height 34px
Player spin boxes (tempo, pitch): minimum height 24px with labels 16px
Total player widget height: Minimum height 350px, will be enforced again after layout restore.
Loop widget („New Songs“): minimum height 240px, buttons 52px, fixed spacing 6px
Prevents unreadable UI on small screens or with high DPI scaling (e.g. 1.8x)

Song Data: ScrollArea (TIC-0012)

The Song Data widget now has a vertical scroll bar instead of being squashed when the dock is small.
All fields remain readable regardless of the widget height.

Bugfix: "Title" column not translated (TIC-0009)

The "Title" column in Playlist and Planner is now correctly displayed via the translation system ("Title" in English).

Bugfix: Show/Hide buttons are now true toggles (TIC-0010, TIC-0011)

_toggle_dock() Previously, only Show + raise was displayed — second click did not hide it.
The Planner and Lyrics buttons now hide their respective docks again on the second click.
Special case of the last tab in the stack: the dock is only brought to the front, not hidden.
Sorting pre-selection in Planner now only works when opening, not when closing.

0.42 — Rules extensions, Planner deletion, App menu & Song display without file (2026-03-28)

New Rule Actions

Go To Position (BL-044): Jumps to the start, loop-in, loop-out, or end of the song. Position selectable via dropdown menu; uses crossfade parameters for a smooth transition.
Toggle Loop Active (BL-045): Toggles the loop checkbox on/off — controllable via keyboard shortcut or rule

Planner: Delete entire playlist (BL-049)

New red ✖ button above the confirmation button in Planner
Deletes the entire playlist after the query dialog

Song data without audio file (BL-051)

Song data and lyrics are now also displayed when no MP3/audio file is present.
The filename field is highlighted in red as a visual indicator.
Warning now only appears in the status bar (no more blocking popup)
Allows manual linking of a file or viewing of migration data.

App Menu (BL-052)

New first menu item „App“ with „Exit“ — clean closing via the menu instead of just via the X

Rules widget

New parameter type „choice“ for dropdown selection in rule actions (e.g., GoTo position)

0.41 — Song Management, Photo Widget, RTF Cleanup & MDB Extension Tables (2026-03-27)

Delete song (BL-039)

Songs can be deleted individually from the database.
Security prompt with option to delete history data (play_history, song_location_stats).
Also accessible via the Delete key in the song list.

Multi-file import with type selection

When importing new songs, the song type is queried beforehand (Pattern / Singing / Both)
Multiple files can be selected simultaneously (multi-file dialog)
The selected type will be applied to all imported songs.

Photo widget (BL-041)

New Dock widget with camera preview (QtMultimedia: QCamera + QMediaCaptureSession)
RAM-only: Photos are only stored in memory, no file system, no database.
Lazy init: The camera is only initialized when the dock is first visible.
QStackedWidget for switching between camera preview and captured photo
Rules actions: photo_capture (start camera + timer) and photo_show (90% screen)

RTF Cleanup (BL-043)

Lyrics import: Word junk from RTF files is automatically removed (datastore, themedata, colorschememapping, xmlnstbl, latentstyles etc.)
Whitelist approach: Only known RTF groups (fonttbl, colortbl, stylesheet) are retained.
Up to 48% file size saved on affected files

MDB Migration: Extended Tables (BL-047)

access-parser monkey patches for extended CC1 tables (off-by-one, row count, primary key)
History-Based Reconstruction: If normal song fields are unreadable, songs are reconstructed from history.
Case-insensitive fallback for table and column names (access parser returns inconsistent uppercase/lowercase results)
Windows Console: Unicode-safe log output (ASCII instead of special characters)

Bug fixes

SqView migration ready for larger test data

0.40 — Loop count, performance optimization & multi-start protection (2026-03-26)

Loop count / Timed loop (BL-042)

New feature: Caller sets desired pattern duration, Caller's Caddy calculates the required number of loops.
Two options (one more loop / one less loop) with resulting total duration
The number of loops is displayed in the player (Loop X/N or Loop infinite).
Singing Calls display "1" instead of an infinity symbol in the Loops column.
Loop count per playlist entry (not per song), persisted in playlist files
Backward-compatible playlist format: Automatically detects old and new formats.
Double-clicking the Loops column opens the Loop Count dialog (Playlist + Planner)

Player improvements

Song title on its own line (16px bold), info line below with timer + loop count + BPM
Loop markers (loop-in / loop-out) are displayed as vertical lines on the position slider.

Playlist + Planner

New column "Duration" with calculated runtime per song (taking loop count into account)
Total duration displayed below the playlist — caller can plan their entire evening.
Planner: Left and right areas can be resized using QSplitter.

Performance optimization (Startup −55%)

App start: 1724ms → 780ms due to lazy initialization of Reports, Potential and Planner
Song list: set_last_played_map now only updates the date column instead of rebuilding the table.
Playlist duration: Negative cache + inline total (250 songs: 367ms → 5ms)
Performance logging system: perf_start() / perf_log() / perf_split()
Activated via INI switch debug/performance_logging = true

Multi-start protection

Duplicate app launches are prevented (QLocalServer/QLocalSocket)
Error message if Caller's Caddy is already running
Wait cursor (hourglass) during app startup

Translations

New keys: header_duration, playlist_total, loop_count_per_loop, loop_count_before, loop_count_after, already_running

0.39 — SqView migration, song volume & improvements (2026-03-26)

SqView Migration (Beta)

New migration path: SqView → Callers Caddy 2.0
Reads sqview.db: Songs (Tempo, Pitch, Volume, Loops), playback history, lyrics assignments
Auto-Detect: Music and lyrics folders are recognized from SqView-INI.
Detailed log per song: MP3 status, lyrics, loop points, pitch, volume
Follow-up report at the end: missing MP3s and lyrics listed
Beta warning: "Still in the testing stage. Use at your own risk!"„
Filename parsing: "Title-Label.mp3" is automatically split into title + label.

Song volume

The volume field in song data is now applied to the audio engine (multiplicatively).
Smooth ramp-up during volume changes (~50ms), no crackling or popping.
Debounced DB save: only volume column, no lyrics reload on change
Range limited to 0.0–1.0 (0%–100%)

Rules actions

New feature: „Change Pitch“ (±half tones, configurable step size)
New action: „Change Volume“ (±Factor, configurable step size)

Tutorial Menu

New menu item „Exit all tutorials“ (counterpart to „Reset all“)
Ends the current tutorial and marks all tutorials as completed.

Potential Widget

FlowLayout for check buttons: Buttons have full text width, automatically wrap text when the dock is narrow.
Double-clicking on "Empty Location" opens a location dialog with the affected location pre-selected.

Bugfix

The P and L keys now function in the song list/playlist for type-to-search.
(were previously swallowed by the app-wide event filter, even with rules disabled)
Tempo/pitch changes no longer cause audio crackling (Debounced Save without lyrics reload)

0.38 — Lyrics redesign, tutorials & bug fixes (2026-03-25)

Lyrics widget: As-Is rendering (architectural simplification)

Lyrics are now displayed 1:1 in their original form — just like in a browser or Word document.
White background, regardless of the chosen theme.
All colors (text color, background color, highlights) remain original.
Sanitizer radically simplified: now only CSS link resolution + font size removal
External CSS files (e.g., cuesheet2.css) are automatically inlined.
RTF converter: Support for \highlight (background colors)
RTF converter: Correct handling of *\background and other header groups
New "Auto-Width" button: Scales font size to fit text within the window width.
Auto-width is also available as a Rules action ("Lyrics Auto-Width")

Tutorials

New Tutorial: Loop Finder (6 steps: waveform, search area, search window, analysis, results, apply)
New Tutorial: Rules (7 steps: Rule list, New rule, Name/Active/Once, Triggers, Conditions, Actions, Import/Export)

Song restart

Pressing the play button while a song is playing means restarting from the beginning (seek 0).
No more Stop+Start needed, also usable via F5 rule

Bug fixes

HTML lyrics with external CSS are now displayed correctly (TIC-0001)
RTF lyrics with colors and highlights are displayed true to the original (TIC-0002)
App icon in title bar and Windows taskbar (TIC-0004)
CP1252 encoding fallback when loading playlists (utf-8 error)

Ticket system

New ticket system under 5_Tickets/ for error reports and questions
TICKETS.md provides an overview, with one folder per ticket containing attachments.

0.37 — Rule Engine & Automation (2026-03-24)

Rules engine (new system)

Completely new automation system: Triggers → Conditions → Actions
26 triggersApp lifecycle (start, song started/paused/stopped/resumed/changed), periodic timer, keyboard (F1–F12, Space, L, P), manager closed
9 conditionsSong type (singing/pattern), lyrics present/not present, loop set/not present, location selected/not present, playtime exceeds threshold
25 actionsOpen/Close Dock/Full Screen/Focus, Load Layout, Play/Pause/Stop/Fade Out/Toggle, Auto Advance, Auto Scroll Start/Stop, Change Pace, Status Bar Message, Log Message, System Ping, Warning Background (Traffic Light), Location Dialog, Manager Toggle, Auto Loop Finder
Conditional logic: Flexible AND/OR groups (e.g., "Singing AND lyrics present OR pattern AND loop set")
„"Once per song" option: Rule fires a maximum of once per song.

Rule Editor (new widget)

Dockable editor widget with split layout (rule list on the left, editor on the right)
Search field for filtering by name or trigger
Sortable table: Active checkbox, Name, Trigger, Source (System/User)
Dynamic parameter input fields depending on the action/condition type
Buttons: Add, Duplicate, Delete, Up/Down, Export, Import

System vs. User Rules

13 pre-installed system rules (only the active toggle can be changed, not edited):
Singing Call → Lyrics Fullscreen with Auto-Scroll (Start + Resume)
Singing Call Stop/Pause → Default Layout back
Song Stop → Auto-Advance
Manager closed → Focus on playlist
Keyboard shortcuts: F5=Play, F6=Pause, F7=Stop, F8=Fade-Out, Space=Play/Pause, L=Location, P=Manager
User rulesFully editable, import/export as JSON, freely sortable

Rule logging

Own log file rules/rules.log with categories: TRIGGER, MATCH, NO_MATCH, ACTION, ERROR, BLOCKED
Automatic rotation at 1 MB (retains 500 lines)
Helps diagnose why rules fire or don't fire.

Auto Loop Finder (Rule Action)

New promotion auto_set_best_loopAutomatically analyzes the song and sets the best 64-beat loop.
Prefers 64-beat loops, fallback to highest score
„"Please wait" overlay during analysis (semi-transparent, disappears automatically)
Can be triggered automatically via a rule, e.g., when a song starts?

Performance optimization

Lazy WaveformLoop finder waveform is only loaded when visible (saves ~100-400ms when changing songs)
Targeted song updateAfter playback, only the Last Played column is updated instead of rebuilding the entire song list (~4-22ms instead of ~400-1200ms)

Loop widget: New button layout

All 4 buttons (Set In, Clear, Set Out, Test Loop) in one flat row
Buttons shrink when space is limited, with automatic text wrapping.
The player column can now be made significantly narrower.

Dock widget improvements

Feature persistenceDocking capabilities (move/dock/close) are retained after layout restoration (Qt bug fixed)
Smaller window sizesDocks can now be docked even when the app is not running in full screen (minimumSize fix)

Bug fixes

Loop-GuardSnapshot values of 0.0 are correctly identified as invalid — preventing good loop values from being overwritten on closure.
Audition/Beat SnapPlayback in Loop Finder and Beat Snap will no longer be logged in the play history.
Close Loop Finder: Automatically stops current playback
Resume rule: Works reliably again after layout change (Focus-Restore after restoreState)

0.36 — Loop Finder & UI Reorganization (2026-03-21)

Loop Finder (new widget)

New dockable window „Loop Finder“ — automatically searches for suitable loop points.
Similarity-based analysis: Compares phrases in the front and back of the song.
8-beat numbering: All beats are numbered 1-8, jumps only between the same beat positions.
Downbeat detection: Prefers candidates on estimated beat 1 (kick energy heuristic)
Chroma-based harmony score (FFT → 12 semitones, using only Scipy/NumPy)
Adjustable comparison window: 4, 8, 16, 32 or 64 beats per ComboBox
Adjustable search areas: 4 percentage fields (Default 7%/21%/64%/79%) with reset button
Waveform overview with colored search areas (green = Loop-In, orange = Loop-Out)
4 movable handles (both sides per region adjustable via mouse)
7 Singing-Call segments above the waveform (Opener, 1-4, Middle Break, Closer)
White dashed lines indicate the selected proposal in the waveform.
Sortable results table: Click on column header to sort by Score, Beat, Time
Audition function: Starts 5 seconds before loop-out, skips, stops 2 seconds after loop-in.
Apply button: Adds the suggestion as a loop-in/loop-out to the player
Analysis runs in QThread (non-blocking)
No new dependencies — everything with Scipy + NumPy

UI reorganization (loop widget)

Loop Active → Player: Checkbox moved from the Loop widget to the player toolbar (to the right of Lyrics)
3-column layoutThe loop-in time and loop-out time are centered above their buttons.
Button row: Set Loop In | Set Loop Out | Test loop next to each other
New row of buttonsLoop Finder | Beat Snap side by side
Fixed row height in the 3-column grid (does not stretch with larger widgets)

Loop Finder Dock

Custom dock widget, must not dock with other widgets (Qt.NoDockWidgetArea)
It opens via the new "Loop Finder" button in the Loop widget.

0.35 — Guided Tutorials & Improved Loop Guard (2026-03-20)

Tutorial system (13 tutorials)

New guided tutorial system with tooltip overlays and highlight frames
11 Widget Tutorials: Player, Layout, Song List, Song Data, Planner, Playlist, Loop, Lyrics, Sequences, Reports, Potential
2 dialogue tutorials: Locations, Beat Snap
Priority-based order: Player → Locations → Layout → Song list → … → Potential
Automatic chaining: After completing one tutorial, the next one is offered.
Tutorial offer can be declined: „Not now“ pauses tutorials for the session.
Step navigation: Next, Previous, Skip + Step indicator (e.g. "3 / 5")
Enter = Continue, Escape = Skip

Tutorial Menu

New submenu "Tutorials" with all tutorials in priority order
Checkmark (✓) next to completed tutorials
„"Reset all tutorials" completely resets your progress.
Menu selection takes precedence over automatic "next tutorial"„
Individual tutorials can be restarted at any time via the menu.

Tutorial Architecture

Three-component system: Transparent overlay (click-catcher) + highlight frame + tooltip popup
Highlight and tooltip as separate tool windows (located above QDockWidgets)
Multi-element highlighting: Frame multiple elements simultaneously (e.g., BPM field + Auto button)
Dialogue tutorials: Custom lightweight engine for modal dialogues (LocationDialog, BeatSnapDialog)
Special paths: _menu_bar, _dock_XXX_title for menu and dock title bars
Floating dock management: Loose docks are hidden during tutorials and restored afterwards.
Tooltip box with its own paintEvent (opaque background despite transparent overlay)
Dedicated skin colors: tutorial_box_bg, tutorial_box_text, tutorial_highlight in all 4 themes

Beat Snap: „Adjust“ → „Snap“

Button label renamed from "Adjust" to "Snap" (including tooltip and status text)

Improved Loop Guard (Database)

Enhanced protection against accidental overwriting of loop values
New Guard 2: Detects the engine reset pattern (loop_in=0 + loop_out=song duration) and protects saved values.
The previous guard only protected against 0.0, not against the song duration as loop_out.

Win11 Theme

Zoom SVG icons: Stroke color changed from dark (#1b1b1b) to white (#ffffff) (better visibility on blue background)

0.34 — Keyboard Shortcuts & Elegant Gold Theme (2026-03-19)

Keyboard shortcuts (app-wide)

L key: Opens location selection dialog (with focus on location list)
P key: Opens/closes Planner (focusing on Pool table)
App-wide EventFilter instead of QShortcut (also works with focused tables/lists)
Modal dialogs automatically block shortcuts
Text fields/SpinBoxes are recognized and not intercepted.
Planner sorting is automatically pre-selected (recommendation for location, quality otherwise)

Elegant Gold Theme

New theme „Elegant Gold“: Anthracite base with radiant gold (#d4a017)
Golden title bars, buttons, active tabs, header separators and tooltips
Deactivated elements in medium gold tone (#7a6a2e)
Input fields and list areas with a light gold tint (#2e2a1f)
SVG icons: Arrows and dock buttons black (#000000), magnifying glass/gear dark brown (#2a2518)
Section-bar segments (Singing Call 1/2/3/5) in medium gold tone

Focus Management

Startup focus on song list (prevents shortcut blockage by SpinBox)
Floating dock activation: activateWindow() before setFocus() for keyboard input
Location dialog: Focus on the list if there are existing entries, on the add button if the list is empty.

Tooltip improvements

Location and Planner buttons display shortcut information in the tooltip (L) / (P)

0.33 — Potential Widget & Menu Redesign (2026-03-18)

Potential widget (data quality)

New dockable window „Potential“ — shows optimization potential in the song database
5 checks with badge counters on the buttons:
Singing Calls without Lyrics
Pattern without loop markers
Loops without BeatSnap optimization
Locations without playback history
Orphaned history entries (deleted locations)
Double-clicking navigates to the affected object (song data, beat snap, location)
„"Ignore" button: Mark individual entries as consciously accepted.
„"Clean all": Delete orphaned history entries in batches
Lazy loading: Data is only loaded when displayed.
DB: New table potential_ignored (check_type + entity_id)

Delete location

The delete function now works correctly (previously blocked by a foreign key).
Checkbox „Also delete history data“ in the confirmation dialog
Without checkbox: History remains as orphaned entries (visible in the potential)
Checkbox selected: History and stats will be completely deleted.

Menu redesign

„"Design" renamed to "Settings" / "Settings"“
Date format setting moved from View to Settings
Language setting moved from Info to Settings
„"Skin" renamed to "Theme" (menu, dialogues)
Date format label: „DE“ changed to „EU“ (valid throughout Europe)

Default layout (3 columns)

New 3-column layout as default on initial installation and layout reset
Column 1: Player at the top, Loop/New at the bottom
Column 2: Song list and playlist as tabs (song list active)
Column 3: Lyrics, song data and sequences as tabs (Lyrics active)
Planner, Reports, Potential hidden (can be opened via menu)

Technically

Layout version 3 (new dock requires layout reset)
Dock setup sequence: First split 3 columns horizontally, then split column 1 vertically.
(prevents the player from spanning the full width)

0.32 — Keyboard, File Selection & Loop Improvements (2026-03-18)

Keyboard & File Selection

ENTER key: Load song into song list, add song from planner pool to playlist, remove song from playlist
Function keys (F5-F8, Space) now also work with undocked windows (Application Shortcut).
File selection button („…“) in song data: Change audio file afterwards
If the file is already in use: Copy dialog with automatic copy creation.
Extended audio format support: WAV, FLAC, OGG, AIFF in addition to MP3
Audio format filter also expanded in the import dialog.
New DB method update_filename() with UNIQUE constraint check

Loop crossfade

Seamless loop transition through crossfade instead of hard cut
Crossfade duration configurable via INI loop/crossfade_ms (Default 46ms)
Eliminates WSOLA transient artifacts at the loop point (no flush/warmup needed)
Budget-based loop mechanism: Callback counts output samples, no stretcher access from UI thread
Fallback protection: Feed-level loop-back if the UI timer misses the seek.

Loop offset (per song)

Automatic offset measurement via FFT-based cross-correlation (low-pass filter <200Hz)
Finds the optimal offset between the loop end and loop beginning in the bass range.
Search range ±2 seconds, selects the smallest offset with good correlation (>= 0.1)
The offset is stored in the database for each song (loop_offset_ms)
Manual fine-tuning via SpinBox in song data (±3000ms, 0.5ms steps)
Automatic measurement during Beat Snap and Loop tests, result in dB + SpinBox
Database migration: New column loop_offset_ms will be created automatically

Bug fixes

The play position display (time + slider) no longer sticks when starting a pattern with a loop.
Loop markers are no longer reset to 0 when changing files.

0.31 — Beat Snap Audition (2026-03-16)

Beat Snap Dialog: Preview the loop jump with waveform visualization
Dual waveform display (loop-out at the top, loop-in at the bottom) with cursor synchronization
Playback sample counter (_playback_sample) in audio engine for precise position determination
Engine loop is deactivated during audition (prevents double jumps due to feed-ahead)
Layout versioning: _LAYOUT_VERSION Prevents corrupted dock states during changes
Versioned saveState()/restoreState() — old state is automatically discarded
Bugfix: Dock widgets could no longer be snapped to the dock after switching from P30 to P31.

0.30 — BPM detection, reports, lyrics contrast (2026-03-14)

Auto-BPM detection via comb filter bank (scipy/numpy, no new packages)
Sub-harmony correction: Check integer multiples, prefer higher tempi.
BPM detection runs in QThread (non-blocking).
Reports widget: Setlist/music sequence list for GEMA with TXT export
Bidirectional ComboBox filtering (location ↔ date)
Lyrics contrast: WCAG-based color recognition for Word HTML (bgcolor, background, color)
Sanitizer removes block backgrounds, retains inline highlights, and replaces poor text colors.
The default stylesheet is updated with every skin change and when setHtml() is called.

0.29 — Release preparation (2026-03-12)

Internationalization: i18n module with JSON translations (German/English)
5-level folder structure: 1_Source, 2_Test, 3_Build, 4_Release, _archive
Build pipeline: PyInstaller-Spec + build.py (full package, update, source ZIP)
Clean DB script: Removes user data, retains reference data (sequences, teaching order)
Migration EXE: Separate Access import process
Portable paths: App directory next to EXE instead of prototype folder

0.28 — Sequence Window + Design Menu + Audio Fix (2026-03-11)

New dockable window „Sequences“ (Dock 9, tabbed with Lyrics)
Import of 885 singing call sequences from Access MDB (caller.mdb)
Cached Live Mapping against Burleson Vocabulary (Teaching Order)
Contains filter: Autocomplete search for contained calls
Limit filter: Only sequences up to a certain program level.
Lazy loading (blocks of 50) for fast scrolling
Detailed dialog with all calls and program tags
Remapping button (gear icon) for recalculating teaching orders
Zoom [-/+] with percentage display (like lyrics widget)
New module: sequence_mapper.py (Burleson mapping logic)
Database extension: sequences + sequence_calls Tables with indexes
Design menu: Load/save/restore layout + skin switching at runtime
Named layouts: Callers can save "Live.ini", "Workshop.ini", etc.
Playlist Manager renamed to "Planner" (shorter, renamed everywhere)
Caller Workflow Guidance: Location → Planner button red → Planner confirmed → Playlist focus
Audio fix: Persistent stream (no crackling/humming at song start)
WSOLA warmup: 200ms settling phase is output as silence

0.27 — Performance optimization (2026-03-11)

Performance measurement framework with Phase A (Baseline) and Phase B (Stress test with 10k songs)
Test methodology: 10 repetitions, statistics (Mean/StdDev/Min/Max), CSV export
Pool table in the playlist manager: 40% faster through optimized table pattern
Song list: 7% faster through the same optimization
Insight: QTableWidget rebuild is the bottleneck, not the database or sorting.
Optimized pattern: setRowCount(0) + setRowCount(n) + setItem() instead of insertRow()

0.26 — Lyrics display (2026-03)

Lyrics widget as a dockable window (tabbed with song data)
Supported formats: HTML/HTM, RTF, TXT
Auto-Fit: Font size is automatically adjusted when text fits on a page.
Auto-scroll: Proportional to the song's progress
Smart color cleanup: Backgrounds removed, section colors retained.
Toolbar with auto-scroll/auto-size toggle and zoom +/-
Light Blue Skin: Second color scheme (light surface, blue accents)
Muted and indicator colors for better contrast in both skins
Loop-save bug fix: Snapshot mechanism saves loop values before song changes
Shared data folders (music/, lyrics/, playlists/) save disk space

0.21 — Playlist and Playlist Manager (2026-03)

PlaylistWidget: Slim, tabbed next to the song list, load/save as .txt
PlaylistManagerWidget: Two-panel view with song pool and playlist mirror
Song transfer: Double-click, arrow buttons, drag & drop
4 sorting options: Alphabetical, Quality, Last played, Recommendation
Filter: All / Pattern only / Singing only
Auto-Advance: Next song at song end, stop or fade-out
Fade-Out: Configurable linear volume ramp (default 3s)
Recommendation system integrated (originally P25)
Integrated playlist builder (originally P24)

0.20 — Playback history (2026-03)

Three-layer architecture: play_history, song_location_stats, on-the-fly calculation
„"Last played" column in the song list
Location-based statistics (when and where each song was played)
Renaming: "Club" becomes "Location" (generalized for Club + Special)
INI setting for date format (German/American)

0.19 — Locations (2026-03)

Club and special administration as selectable contexts
Location selection influences song recommendations and history.

0.18 — Pattern/Singing Mode (2026-03)

Songs can be marked as patterns, singing, or both.
Type abbreviation (P/S/PS) in song list and pool display
Filter by mode in the playlist manager

0.17 — Current pace (2026-03)

Saved tempo per song for tonight
Tempo is automatically restored when a song is loaded.

0.16 — Song list with search (2026-03)

Song list as QTableWidget with real-time search filter
Search by title, label, and filename

0.15 — Portable Paths (2026-03)

Relative paths for songs and data
The application can be moved to a USB stick or between computers.

0.14 — Auto-Save (2026-03)

Automatic saving of all changes (song data, settings)

0.13 — Song Data Model (2026-03)

SQLite database for songs, locations, history
Song fields: Title, Filename, Label, Quality, Pattern/Singing, Tempo

0.07 — Dock Window System (2026-03)

QDockWidget-based windowing system with free arrangement
Move, dock, stack, and resize windows
The layout is saved and restored upon restart.
Resize rules per window type
Integrated: P8 (Show/Hide), P9 (Move), P10 (Resize Rules), P11 (Docking), P12 (Layout Persistence)