
================================================================================
 English Quick Guide
================================================================================
INSTALL   Run copy_fl.bat (copies the script to %USERPROFILE%\Documents\
          Image-Line\FL Studio\Settings\Hardware\AQ64L\), restart FL Studio.
          macOS: run install_mac.command (first time: right-click > Open;
          or Terminal: bash install_mac.command). It installs to
          ~/Documents/Image-Line/FL Studio/Settings/Hardware/AQ64L/.
LOCATION  Windows: the installer reads FL's registry value (Shared data), then
          the default folder (honours a OneDrive-redirected Documents), then
          shows a folder-picker. macOS: default folder, then folder-picker.
          It shows the path and asks to confirm (Enter = install, n = pick
          another folder, q = quit). Custom location, pass FL's user-data
          folder (the one containing "Settings"):
          copy_fl.bat "D:\path\FL Studio"   /   bash install_mac.command "/path/FL Studio"
MIDI    Options > MIDI Settings: enable the FIRST "AQ64L" input (controller
SETTINGS  type "AQ64L (user)") and the FIRST "AQ64L" output, SAME Port number
          on both. The second pair (MIDIIN2/MIDIOUT2) is optional: enable the
          MIDIIN2 input to play USER-mode notes into FL — verified, does not
          affect the control link. Keep its controller type generic; never
          assign "AQ64L (user)" to it.
          On the device: SET menu > MK2 compatibility OFF.
SESSION   Enable Performance mode in the Playlist first. The 8x8 grid mirrors
          the playlist (row = track, column = block/scene); the red frame in
          FL shows the current window. Pads trigger clips (auto-starts Song
          mode playback); blink = scheduled, pulse = playing; pressing an
          empty cell stops that track; press a blinking pad again to force an
          immediate un-quantized start. Right FUNC column = scene launch
          (i-th visible column). Nav keys scroll: up/down = tracks,
          left/right = scenes.
          Note: a MUTED clip (x before its name) never leaves the scheduled
          state — unmute it (middle-click) in FL.
MIXER     Rows: STOP = mute, TRACK = select, SOLO = solo, ARM = record-arm.
          FUNC 1-4 = VOL / PAN / SND A / SND B fader pages (SND A sets route
          send levels to the currently selected track, needs FL 2024+;
          SND B = live VU meters, tap a column to select). FUNC 5 = stop.
          Nav: left/right = bank +/-8, up/down = +/-1. In the STOP sub-mode
          the FUNC column stops every track playing that scene column.
TROUBLE   No LEDs: Port numbers differ or output disabled. Dark grid:
          Performance mode off. Blinking forever: clip is muted in FL.
          SND A inert: FL older than 2024. Logs: View > Script output.
================================================================================

================================================================================
 AQ64L — FL Studio 控制脚本 使用说明 / Usage Guide
 脚本版本 Script version: v0.3  (连接 + MIXER + SESSION/Performance Mode)
 系统要求 Requires: FL Studio 20.7+  (SND A 发送量需 FL 2024+ / API v36)
================================================================================

【本文件夹内容】
  copy_fl.bat                              一键安装脚本
  FL Studio Scripts\AQ64L\device_AQ64L.py  控制脚本本体
  FL Studio Scripts\AQ64L\README.md        完整技术说明（映射细节、已知边界）

--------------------------------------------------------------------------------
一、安装
--------------------------------------------------------------------------------
1. 双击运行 copy_fl.bat —— 自动把脚本拷贝到：
   %USERPROFILE%\Documents\Image-Line\FL Studio\Settings\Hardware\AQ64L\
   安装程序会自己找 FL 的用户数据文件夹，不必手动指定，查找顺序：
     命令行参数 → FL 注册表里的 Shared data → 默认位置（含被 OneDrive 重定向的
     "文档"）→ 弹出文件夹选择框。
   找到后会显示路径并让你确认：直接回车 = 安装；n = 换一个文件夹；q = 退出。
   数据目录在非默认位置又没被识别时，可手动指定（路径 = 含 Settings 的那个文件夹）：
     copy_fl.bat "D:\你的路径\FL Studio"
   （copy_fl.bat 只是启动器，实际工作由同目录的 install.ps1 完成，请勿删除它。）
   （也可手动拷贝"FL Studio Scripts\AQ64L"整个文件夹到上述位置。）
2. 重启 FL Studio。
   （日后更新脚本：重跑 copy_fl.bat，然后 FL 里 View > Script output > Reload script。）

macOS 安装：
1. 运行 install_mac.command（首次请右键 > 打开，以通过 Gatekeeper；
   或在"终端"执行：bash install_mac.command），自动安装到：
   ~/Documents/Image-Line/FL Studio/Settings/Hardware/AQ64L/
   若双击提示"没有权限"，在终端执行 chmod +x install_mac.command 一次即可。
2. 重启 FL Studio（日后更新同样重跑 install_mac.command，再 Reload script）。
   第二节的 MIDI 设置在 macOS 上相同：第一个 AQ64L 输入/输出，Port 号一致。

--------------------------------------------------------------------------------
二、FL 的 MIDI 设置（Options > MIDI Settings）—— 最容易出错的一步
--------------------------------------------------------------------------------
  Input  列表：启用【第一个】AQ64L，Controller type 选 "AQ64L (user)"，
               Port 填一个数字（例如 10）
  Output 列表：启用【第一个】AQ64L，Port 填【同一个数字】
               （两边 Port 不一致 = 设备灯光全无）
  第二对端口（MIDIIN2 / MIDIOUT2 AQ64L）：可选——启用 MIDIIN2 输入后，
               USER 模式可当琴键弹进 FL（实测不影响控制链路）；
               其 Controller type 保持默认，切勿再选 "AQ64L (user)"
  设备端：SET 菜单里 MK2 兼容开关必须关闭

  配置正确后脚本自动握手，设备进入 SESSION 模式
  （Script output 窗口打印 "init ok"，FL 提示栏显示 "AQ64L connected"）。

--------------------------------------------------------------------------------
三、SESSION 模式 = FL Performance Mode（现场触发 clip）
--------------------------------------------------------------------------------
前提：Playlist 左上角下拉菜单勾选 Performance mode，并把 Pattern/Audio clip
      摆进演出区（"开始/Start"时间标记左侧）。未开启时网格全暗，按 pad 会提示。

  8×8 pad     触发对应 clip。网格 = FL 播放列表缩略图：行=轨道、列=block/scene，
              FL 播放列表里的红框实时标出当前 8×8 视窗。
              触发会自动切到 Song 模式并启动播放，无需碰鼠标。
  pad 灯      clip 原色；闪烁 = 已排程等待量化点；呼吸 = 播放中；暗 = 空。
              按空格子 = 停止该轨（FL 原生行为）。
              闪烁等待中【再按一次】= 跳过量化立即起播（演出逃生门）。
  右侧 FUNC 列  scene launch：第 i 个键触发视窗内从左数第 i 列（整列齐发）。
              绿灯 = 该列在视窗内有 clip。
  方向键      ▲▼ = 上下移 1 轨；◄► = 左右移 1 个 scene；
              LED 亮 = 该方向还有内容。红框跟随移动。

★ 已知注意：clip 名字前有 ✕（被静音）时，触发只会一直闪、不会起播——
  这是 FL 对静音 clip 的行为，鼠标中键点掉 ✕ 即恢复。

--------------------------------------------------------------------------------
四、MIXER 模式（按设备 MIXER 模式键进入）
--------------------------------------------------------------------------------
对应 FL 混音台 insert 1-8（一个 bank 8 轨）：

  STOP  行    静音开关（LED = 已静音）
  TRACK 行    选中混音台轨道（LED = 当前选中）
  SOLO  行    独奏开关
  ARM   行    预备录音开关
  FUNC 1-4    进入 VOL / PAN / SND A / SND B 推子子模式（再按同键退出）
  FUNC 5      停止播放（transport stop）
  ◄ ►         bank ±8；▲ ▼ bank ±1（LED 亮 = 还能移动）

推子子模式：
  VOL    音量（FL 满增益 = 0.8 位置）
  PAN    声像（中点 = 64，两键夹按可归中）
  SND A  发送量：先在 FL 里选中目标轨（如混响总线），每列 = 该轨发往选中轨
         的 route 量；列暗 = 无路由。需 FL 2024+，旧版按下会弹提示。
  SND B  VU 表页：8 轨实时峰值；点按某列 = 选中该轨。
  STOP 子模式下 FUNC 列 = 按 scene 停止（停掉所有正在播该列的轨道）。

--------------------------------------------------------------------------------
五、故障排查
--------------------------------------------------------------------------------
  灯光全无            → Input/Output 的 Port 号不一致，或 Output 没启用
  网格全暗            → Playlist 的 Performance mode 没开
  按 pad 只闪不播     → clip 被静音（名字前有 ✕），中键取消静音
  SND A 没反应        → FL 版本低于 2024（API v36）
  设备没进 SESSION    → 设备 SET 菜单里 MK2 兼容开关没关
  看运行日志          → FL 菜单 View > Script output > AQ64L 标签页
  FL 卡死/假死 >45 秒 → 设备变灰属正常保护，FL 恢复后自动重连重画

