Files

T

3dtours d5143b440a fix: change md files to md folder

2026-07-21 18:22:39 +07:00

7.6 KiB

Raw Blame History

Dưới đây là toàn bộ nội dung tài liệu đặc tả kỹ thuật đã được chuyển đổi sang định dạng Markdown chuẩn, tối ưu hóa các khối mã nguồn (python, text), căn chỉnh bảng biểu và định dạng các công thức toán học LaTeX:

Đặc Tả Kỹ Thuật: Hành Động Chọn Vùng & Cơ Chế Phát Lặp (Solo vs. Master Loop)

Tài liệu này đặc tả cơ chế tương tác chuột và logic phát âm thanh tương ứng đối với hai vùng chọn: Chọn cục bộ trên Track (Local Selection) và Chọn toàn cục trên Timeline (Global Selection) dựa trên thiết kế chuẩn DAW trong hình image_dfffa3.png.

Mục tiêu là cung cấp thuật toán xử lý sự kiện chuột (MouseEvent) để lập trình viên chuyển đổi (port) trực tiếp sang Python (ví dụ sử dụng QGraphicsView hoặc QWidget tùy biến trong PyQt6/PySide6).

1. Bản Vẽ Phân Cấp Vùng Tương Tác (Layout Hitboxes)

Dựa trên hình image_dfffa3.png, khu vực biên tập bên phải được phân chia thành 2 hitbox tương tác chuột chính yếu:

+-------------------------------------------------------------------------+
| [VÙNG A] TIMELINE RULER (Thước đo thời gian trên cùng - Mũi tên đỏ chỉ)  |
+-------------------------------------------------------------------------+
| [VÙNG B] CÁC LÀN TRACK LANE (Xếp chồng dọc)                             |
|  - Track 01 Waveform Area (Hitbox cục bộ 1)                             |
|  - Track 02 Waveform Area (Hitbox cục bộ 2)                             |
|  - Track 03 Waveform Area (Hitbox cục bộ 3)                             |
+-------------------------------------------------------------------------+

2. Đặc Tả Tương Tác 1: Chọn Cục Bộ & Phát Lặp Độc Lập (Local Track Selection & Solo Loop)

2.1. Hành động người dùng (User Action)

Click chuột đơn (Mouse Press): Người dùng nhấp chuột vào một điểm bất kỳ trên dạng sóng của một track (Ví dụ: Track 01).
Hệ quả: Track đó lập tức được highlight (Active State), các track khác chuyển sang trạng thái chờ.
Kéo chuột (Mouse Drag): Click và nhấn giữ chuột, kéo sang trái hoặc phải trên phần hiển thị sóng âm của track đó.
Hệ quả: Tạo ra một vùng chọn thời gian giới hạn bởi điểm nhấn đầu và điểm thả chuột cuối.

2.2. Cơ chế phát lặp (Loop Playback Logic)

Chế độ phát: Khi nhấn nút Play Loop, hệ thống chỉ phát lặp duy nhất đoạn nhạc nằm trong vùng chọn của track đang active.
Xử lý Audio Engine ở Python:
Tự động kích hoạt cơ chế Mute tạm thời cho tất cả các track khác, hoặc kích hoạt nhanh chế độ Solo cho track đang active trong luồng phát âm thanh.
Giới hạn mốc thời gian phát trong khoảng T_{\text{start}} đến T_{\text{end}}. Khi kim phát phát chạm T_{\text{end}}, nhảy ngay lập tức về T_{\text{start}} mà không dừng phát các luồng khác (nếu có).

2.3. Ánh xạ mã sự kiện Python (PyQt6 / PySide6 Concept)

# Giả lập xử lý sự kiện trong lớp TrackWaveformWidget(QWidget)

def mousePressEvent(self, event):
    if event.button() == Qt.MouseButton.LeftButton:
        # 1. Kích hoạt chọn track hiện hành
        self.parent_session.set_active_track(self.track_id)
        # 2. Ghi nhận điểm mốc thời gian bắt đầu
        self.drag_start_time = self.pixel_to_time(event.position().x())
        self.is_dragging = True

def mouseMoveEvent(self, event):
    if self.is_dragging:
        current_time = self.pixel_to_time(event.position().x())
        # Cập nhật vùng chọn cục bộ (Local Selection Range)
        self.parent_session.update_local_selection(
            track_id=self.track_id, 
            start=min(self.drag_start_time, current_time),
            end=max(self.drag_start_time, current_time)
        )

3. Đặc Tả Tương Tác 2: Chọn Toàn Cục & Phát Lặp Đa Kênh (Global Timeline Selection & Master Loop)

3.1. Hành động người dùng (User Action)

Định vị: Di chuyển con trỏ chuột lên trên cùng, vào thanh chứa Timeline Ruler (Vị trí mũi tên màu đỏ trong hình image_dfffa3.png).
Kéo chuột (Mouse Drag): Click chuột vào thanh Ruler và kéo sang trái/phải.
Hệ quả: Một khung màu cam nhạt (Selection Overlay) xuất hiện và kéo dọc toàn bộ chiều cao màn hình xuyên qua tất cả các track từ trên xuống dưới (như hiển thị thực tế trong hình image_dfffa3.png).

3.2. Cơ chế phát lặp (Loop Playback Logic)

Chế độ phát: Khi nhấn nút Play Loop, hệ thống sẽ phát đồng thời tất cả các track (Master Playback) nhưng giới hạn vòng lặp đồng bộ chỉ nằm trong dải thời gian được bôi màu.
Xử lý Audio Engine ở Python:
Giữ nguyên trạng thái Mute/Solo hiện tại của các track (không tự động tắt tiếng các track khác).
Đồng bộ hóa pha của tất cả các luồng phát. Khi Playhead chạm mốc kết thúc vùng chọn T_{\text{end}}, toàn bộ các nguồn phát (Audio Sources) đang hoạt động đều phải nhảy đồng bộ về vị trí T_{\text{start}}.

3.3. Ánh xạ mã sự kiện Python (PyQt6 / PySide6 Concept)

# Giả lập xử lý sự kiện trong lớp TimelineRulerWidget(QWidget)

def mousePressEvent(self, event):
    if event.button() == Qt.MouseButton.LeftButton:
        # Ghi nhận mốc thời gian toàn cục ban đầu
        self.global_drag_start = self.pixel_to_time(event.position().x())
        self.is_dragging_global = True
        # Hủy bỏ các vùng chọn cục bộ (nếu có) để ưu tiên chế độ chọn tổng thể
        self.parent_session.clear_all_local_selections()

def mouseMoveEvent(self, event):
    if self.is_dragging_global:
        current_time = self.pixel_to_time(event.position().x())
        # Cập nhật vùng chọn toàn cục xuyên suốt tất cả các làn track
        self.parent_session.set_global_selection(
            start=min(self.global_drag_start, current_time),
            end=max(self.global_drag_start, current_time)
        )

4. Tóm Tắt Sự Khác Biệt Giữa 2 Trạng Trạng Thái

Để đảm bảo hệ thống không bị xung đột khi xử lý đa luồng âm thanh trên Python Docker, bộ điều phối âm thanh (Audio Coordinator) cần tuân thủ bảng logic sau:

Thuộc tính	Tương tác trên Track (Local)	Tương tác trên Ruler (Global)
Phạm vi hiển thị vùng chọn	Chỉ hiển thị hoặc sáng rõ tại track đang active.	Kéo dài thẳng đứng, phủ qua tất cả các track (như hình `image_dfffa3.png`).
Phạm vi phát âm thanh	Solo Playback: Chỉ phát duy nhất âm thanh của track được chọn.	Master Playback: Phát tất cả các track cùng lúc (không tự động Solo/Mute).
Điểm lặp (Loop Target)	`T_{\text{start}} \rightarrow T_{\text{end}}` của riêng track hoạt động.	`T_{\text{start}} \rightarrow T_{\text{end}}` toàn cục đồng bộ tất cả các track.
Phục vụ AI Cut	Chỉ cắt tệp tin của riêng track được chọn để đưa sang track mới.	Cho phép render/mixdown gộp tất cả các track trong dải chọn thành tệp mới.

7.6 KiB Raw Blame History