

# 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
<!-- Main Container (Entire Editor Wrapper) -->
<div class="flex flex-col h-full overflow-hidden">
  
  <!-- [ZONE A] Top Anchored Sticky Header Zone -->
  <div class="sticky top-0 z-40 bg-[#242424] border-b border-[#141414] shrink-0">
    <!-- Toolbar & Time Ruler -->
    <div class="h-8 flex">
      <div class="w-[300px] border-r border-zinc-900 px-4 flex items-center">CHANNELS</div>
      <div class="flex-1 relative h-full">...Ruler Numbers...</div>
    </div>
    <!-- Tempo Track (Green Border Area) -->
    <div class="h-[44px] flex border-t border-zinc-800 bg-[#212121]">
      <div class="w-[300px] border-r border-zinc-900 px-4 flex items-center justify-between">
        <span class="font-bold text-zinc-400">Tempo Track</span>
        <span class="bg-zinc-800 px-1.5 py-0.5 rounded text-[10px]">120 BPM</span>
      </div>
      <div class="flex-1">...Tempo Grid Lines...</div>
    </div>
  </div>

  <!-- [ZONE B] Dynamic Track Workspace (Single global vertical scrollbar on the far right) -->
  <div class="flex-1 overflow-y-auto bg-[#1a1a1a]">
    <div class="flex flex-col divide-y divide-[#141414]">
      
      <!-- Track Row Container (Absolute Horizontal Row Alignment) -->
      <div class="h-[96px] flex hover:bg-zinc-800/20 transition-colors">
        <!-- Left: TCP -->
        <div class="w-[300px] border-r border-zinc-900 p-2.5 flex-shrink-0">
          ...Controls (Mute, Solo, Volume, File Name)...
        </div>
        <!-- Right: Waveform Lane -->
        <div class="flex-1 relative overflow-hidden">
          ...Waveform Canvas...
        </div>
      </div>

      <!-- Add more track rows repeating the structure above... -->
      
    </div>
  </div>
</div>

```

### 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