# Technical Specification: Multi-Channel Layout Synchronization & Scroll Management (Unified DAW Layout & Sync Scroll) This document analyzes and defines the structural hierarchy of the graphical user interface based on the real-world interface analysis. This specification serves to guide Frontend interface programming and porting to a Python Desktop application running inside a Docker container. --- ## 1. Structural Wireframe Based on the visual analysis, the layout composition is split into vertically static and dynamic zones: ```text +───────────────────────────────────────────────────────────────────────────────+ | [ZONE A - STATIC] HEADER ZONE (Sticky - Permanently fixed when scrolling down)| | +────────────────────+──────────────────────────────────────────────────────+ | | | Channels & Tools | Time Ruler Scale | | | |--------------------|------------------------------------------------------| | | | Tempo Track Header | Tempo Grid Lane (120 BPM) | | | +────────────────────+──────────────────────────────────────────────────────+ | +───────────────────────────────────────────────────────────────────────────────+ | [ZONE B - DYNAMIC] TRACKS SCROLL WORKSPACE (Synchronized vertical scroll) | | +────────────────────+──────────────────────────────────────────────────────+ | | | TCP - Track 01 | Waveform Lane - Track 01 | | | | TCP - Track 02 | Waveform Lane - Track 02 | | | | TCP - Track 03 | Waveform Lane - Track 03 | | | | ... | ... | | | +────────────────────+──────────────────────────────────────────────────────+ | +───────────────────────────────────────────────────────────────────────────────+ ▲ │ [Vertical Scrollbar] │ (Single unified scroll) ▼ ``` --- ## 2. Layout Specifications ### 2.1. Fixed Header Zone (Green Border Area - Sticky Header) * **Visual Scope:** Encompasses the toolbar, the time ruler scale, and the Tempo Track Lane (indicated by the green bounding border in `image_fbbd4e.png`). * **Graphical Sticky Behavior:** * When a user adds dozens of tracks and scrolls downward, this entire zone must remain anchored to the top of the screen and is not permitted to slide out of view. * This ensures that users can continuously track the Ruler Seconds and the master project tempo (Tempo BPM) while editing tracks located deeper down the timeline. ### 2.2. Absolute Horizontal Row Alignment (Red Border Area - Row Alignment) * **Interaction Scope:** The exact matching pair consisting of the left Track Control Panel (TCP) and the right Waveform Lane of the same track (e.g., Track 4 inside the red border of `image_fbbd4e.png`). * **Row Alignment Rules:** * The corresponding TCP and Waveform Lane must have identical heights ($H = 96\text{ px}$). * These two elements must be wrapped within a single parent row container (`Flex Row` or `Grid Row`) to guarantee that during vertical scrolling, both move simultaneously along the exact same vertical axis coordinate ($Y$). * Row misalignment must be strictly avoided (e.g., situations where the Track 4 TCP sits higher or lower than the Track 4 Waveform lane). ### 2.3. Single Vertical Scrollbar Mandate * **Issue to Avoid:** Separating the TCP into an independent scrollable column and the Timeline into another independent scrollable column. Doing so leads to scroll-position desynchronization errors when a user drags the scrollbar. * **Design Standard:** * Only a single unified Vertical Scrollbar is permitted to appear on the absolute far right of the application window (as directed by the two red arrows in `image_fbbd4e.png`). * This vertical scrollbar moves the entire dynamic wrapper (**Tracks Scroll Workspace**), scrolling both TCPs and Waveform Lanes up or down in sync. --- ## 3. Implementation Guide ### 3.1. Web Frontend Integration (HTML / Tailwind CSS) To group everything into one scrollbar while keeping the Tempo Track anchored at the top, use `position: sticky` and wrap the dynamic track list inside a single container: ```html
CHANNELS
...Ruler Numbers...
Tempo Track 120 BPM
...Tempo Grid Lines...
...Controls (Mute, Solo, Volume, File Name)...
...Waveform Canvas...
``` ### 3.2. Desktop App Integration (Python PyQt6) When engineering this user interface using the Qt framework in Python, utilize a `QScrollArea` to encapsulate a `QWidget` managed by a layout of rows to control the single scrollbar behavior: ```python from PyQt6.QtWidgets import QWidget, QVBoxLayout, QHBoxLayout, QScrollArea, QLabel from PyQt6.QtCore import Qt class MasterDAWWidget(QWidget): def __init__(self): super().__init__() self.main_layout = QVBoxLayout(self) self.main_layout.setContentsMargins(0, 0, 0, 0) self.main_layout.setSpacing(0) # 1. Initialize Fixed Header (Toolbar, Ruler, Tempo) self.header_widget = QWidget() self.header_widget.setFixedHeight(76) # 32px Ruler + 44px Tempo self.setup_header_ui() self.main_layout.addWidget(self.header_widget) # 2. Initialize Scroll Area for dynamic track rows self.scroll_area = QScrollArea() self.scroll_area.setWidgetResizable(True) # Force a single vertical scrollbar on the far right self.scroll_area.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn) self.scroll_area.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) # Widget container hosting the track list inside the Scroll Area self.tracks_container = QWidget() self.tracks_layout = QVBoxLayout(self.tracks_container) self.tracks_layout.setContentsMargins(0, 0, 0, 0) self.tracks_layout.setSpacing(0) self.tracks_layout.setAlignment(Qt.AlignmentFlag.AlignTop) self.scroll_area.setWidget(self.tracks_container) self.main_layout.addWidget(self.scroll_area) def add_track_row(self, track_id, track_name): """ Appends a new track row. Uses QHBoxLayout to lock the TCP and Waveform Lane into absolute horizontal sync within the row. """ row_widget = QWidget() row_widget.setFixedHeight(96) # Rigid constraint for the entire row row_layout = QHBoxLayout(row_widget) row_layout.setContentsMargins(0, 0, 0, 0) row_layout.setSpacing(0) # Left: Track Control Panel (TCP) tcp_widget = QWidget() tcp_widget.setFixedWidth(300) # Setup TCP UI components... row_layout.addWidget(tcp_widget) # Right: Waveform Lane waveform_widget = QWidget() # Setup Waveform Canvas Painter... row_layout.addWidget(waveform_widget) self.tracks_layout.addWidget(row_widget) ``` --- ## 4. Layout Architecture Advantages * **Fluid User Experience:** Eliminates row-stuttering or scrolling layout shifts between the control panels and audio visuals when a user scrolls through long track stacks rapidly. * **Flawless Python Porting Compatibility:** By wrapping the TCP and the Waveform Canvas inside a common row (`QHBoxLayout` in Qt or `Flex Row` in Web), the core widget tree hierarchy remains incredibly lean. This design removes the need to write custom coordinate bridging code to bind two separate scroll engines together. * **Clean Interface Aesthetics:** Safely protects the pixel rendering mapping ratios of the fixed time grids at the top, precisely matching the professional DAW interface conventions observed