PulseGrid

AI does not just pick the next track. It builds the handoff.

A first-of-its-kind open-source, AI-native DJ workstation that connects track analysis, structure-aware cueing, set planning, transition audit, and automated performance in one local workflow.

AI 不只是帮你选择下一首歌，而是参与每一次接歌。PulseGrid 把歌曲分析、结构化 Cue、Set 编排、转场审计和自动演出放进同一套本地工作流。

中文说明 · English · Download / Releases

_{双 Deck、结构化 Cue、Set Tracklist、转场校验和 Auto Play 全部在同一个工作区。Dual decks, structure-aware cues, transition review, and Auto Play in one workspace.}

From raw tracks to a performance-ready set: Analyze → Understand structure → Plan Cue 8 → Cue 5 → Preview & audit → Auto Play

PulseGrid is not another end-of-song crossfader. It analyzes BPM, key, beatgrid, energy, double drops, and musical sections; builds a set from a natural-language brief; exposes every planned handoff for review; and then performs the approved transitions while driving EQ, Filter, FX, and the Crossfader. Every Cue remains visible and editable by the DJ.

Your music stays yours. The app, analysis engine, uploads, and results run locally. This repository contains no songs, prebuilt Library, historical projects/, user uploads, or generated DJ sets.

---

中文说明

产品简介

PulseGrid 是一套在本机浏览器中运行的开源 AI-native 双 Deck DJ 工作站。它不仅提供专业 DJ 软件常见的波形、Sync、Cue、Loop、EQ、FX 和混音控制，还让 AI 介入从单曲分析到整场演出的完整链路。

你可以上传自己的歌曲，分析 BPM、调性、Beatgrid、能量、双 Drop 和段落结构；再用自然语言描述想要的时长、风格和能量曲线，让系统基于 Library 中已分析的歌曲规划曲序、每一对歌曲专属的 Cue 8 → Cue 5 接歌点，以及 EQ / Filter / FX / Crossfader 自动化。

PulseGrid 采用本地优先设计：网页、分析服务、音频和分析结果都在你的电脑上运行和保存，不需要把歌曲上传到第三方云服务。

为什么它不只是 Auto Mix

常见 Auto Mix	PulseGrid
常在歌尾淡出、歌头淡入	根据段落、Phrase、Drop 和能量选择专属接歌点
接歌决定隐藏在黑盒中	Cue 8 → Cue 5 在 Deck 与 Tracklist 中可见、可试听、可修改
使用统一的淡入淡出曲线	为每一组相邻歌曲规划 EQ、Filter、FX 和 Crossfader 动作
播放一个排序后的歌单	根据自然语言需求创建完整 Set 和能量叙事
自动播放后只能等待结果	先 Preview 和 transition audit，再确认 Auto Play；随时可手动接管

这套设计的重点不是让 AI 取代 DJ，而是把原本耗时的分析、找点、试接和编排变成一套透明、可校验、可编辑的协作流程。

主要功能

双 Deck 与基础混音

• Deck A / Deck B 双卡布局
• 整体波形和滚动放大波形
• BPM 检测、Sync、节拍相位与 Master Deck
• Beatgrid、Tap BPM、Grid nudge、BPM ×2 / ÷2
• 调性检测、Camelot 显示、Key Sync 和 Key Shift
• Tempo / Pitch fader、Pitch Bend、Master Tempo
• 三段 EQ、双向 Filter、Channel fader、等功率 Crossfader 和 Master limiter
• Jog / Scratch、Seek、Slip、Quantize

Cue、Loop 与 Beat 操作

• 每首歌曲最多 8 个 Hot Cue
• Memory Cue
• Auto Loop / Manual Loop
• Beat Jump
• Cue 可由用户覆盖或清除

分析阶段会识别用于人工打碟的结构 Cue。Cue 5 和 Cue 8 不会在单曲 Analyze 时被强制设置成歌曲开头和结尾；它们在创建 Set 时根据相邻歌曲和具体转场生成：

• Cue 5 / AUTO IN：这首歌接上一首歌时的进入点
• Cue 8 / AUTO OUT：这首歌接下一首歌时的退出点
• Set 第一首不要求 Cue 5
• Set 最后一首不要求 Cue 8

FX 与音频处理

• Echo、Reverb、Flanger、Gate 和 Filter FX
• Beat division / 节拍同步参数
• Deck A / B 的 FX Rack 默认收起，可分别展开
• 转场期间可自动控制 High / Mid / Low、Filter、Echo 和 Crossfader
• 浏览器主输出录音

Library

• 上传本地歌曲
• 搜索、排序、评分和标签
• Crate、Smart List 和分析状态
• BPM、Key、波形、能量和结构预分析
• Library 初始为空，不包含演示歌曲或虚构歌单

Set Creation 与 Auto Play

1. 在 Library 中上传并 Analyze 歌曲。
2. 点击 CREATE / SET CREATION，描述期望时长、风格、能量曲线或结尾方式。
3. bass-set-maker 基于已经分析好的曲目生成曲序、播放速度、转场类型、Cue 8 → Cue 5 接歌点及 transition audit。
4. Tracklist 会显示 Deck、Cue、BPM、调性、转场方式及 EQ / Filter / FX automation。
5. 两首歌曲之间可使用 CHECK A8→B5 / Preview，把前后歌曲装入 A/B Deck，试听实际转场。
6. 通过校验后，AUTO PLAY 会按 A → B → A 的 Deck 轮换自动装载和播放歌曲，并在接歌时执行规划好的控制器变化。
7. Tracklist 支持单曲删除、替换和整条清空；修改后会重新规划受影响的转场。

如果你手工修改 Cue 5 或 Cue 8，后续校验和 Auto Play 会使用新的 Cue。运行中的 Cue 或 Deck 操作可能会把控制权交回手动模式，以避免系统在未知状态下继续自动接歌。

下载与安装

方案 A：Docker（推荐）

Docker 能把 Node.js、Python 和系统音频依赖放在一致的运行环境里，是在另一台 Mac、Windows 或 Linux 电脑上使用 PulseGrid 最省事的方式。

需要先安装：

• Git（如果使用 git clone）
• Docker Desktop 或兼容的 Docker Engine

从 GitHub 下载：

git clone https://github.com/ysy-ym/pulsegrid.git
cd pulsegrid

也可以在 GitHub 仓库页面点击 Code → Download ZIP，下载并解压后进入 pulsegrid 目录。

首次启动：

./scripts/start-docker.sh

Windows PowerShell 也可以运行：

.\scripts\start-windows.ps1

或者直接运行：

docker compose up --build

构建完成后打开：

http://127.0.0.1:4173/digital-mixer/

停止服务可在运行窗口按 Ctrl+C。以后再次启动通常可以使用同一条命令；Docker 会复用已经构建的镜像层。

Docker 模式会把本地上传和分析 job 保存在名为 pulsegrid-runtime 的 Docker volume 中。普通的 docker compose down 不会删除这些数据；只有显式删除该 volume（例如使用 docker compose down -v）才会清空它。

方案 B：macOS 本地安装

本地模式适合希望直接使用本机 Python、FFmpeg，或需要开发和调试的人。

准备条件：

• macOS
• Homebrew
• 可联网下载开源依赖

进入仓库目录并运行一次安装脚本：

./scripts/setup-macos.sh

安装完成后启动：

./scripts/start-macos.command

也可以在 Finder 中双击 scripts/start-macos.command。随后打开：

http://127.0.0.1:4173/digital-mixer/

安装脚本会为当前仓库准备隔离的 Python 环境和必要依赖。不要把另一台电脑上的 .venv 复制过来；虚拟环境通常包含与操作系统、CPU 和绝对路径绑定的内容。

方案 C：GitHub Releases

如果仓库已经发布 Release：

1. 打开仓库右侧的 Releases。
2. 选择最新版本。
3. 下载发布的 ZIP 包或 GitHub 提供的 Source code (zip)。
4. 解压后按上面的 Docker 或 macOS 步骤启动。

Release 包同样不会包含歌曲、Library 或其他用户数据。首次打开时 Library 为空。

第一次使用

1. 启动服务并用 Chrome 或 Edge 打开 PulseGrid。
2. 点击 UPLOAD / ADD MUSIC，选择你有权使用的本地音频。
3. 等待 Analyze 完成。分析会生成 BPM、Key、Beatgrid、波形、能量、结构以及人工辅助 Cue。
4. 把歌曲载入 Deck A 或 B，即可手动混音。
5. 需要自动编排时，点击 CREATE，输入 Set 要求并生成 Tracklist。
6. 先用相邻歌曲间的 Preview 校验接歌效果，再启动 AUTO PLAY。

支持的常见格式包括 WAV、MP3、AIFF、M4A、AAC、FLAC、OGG 和 Opus。单文件本地上传上限为 600 MB。

快捷键与 Cue 操作

• 单独轻按左 Shift：播放 / 暂停 Deck A
• 单独轻按右 Shift：播放 / 暂停 Deck B
• Shift + 点击 Hot Cue：用当前播放位置覆盖该 Cue
• 右键点击 Hot Cue：清除该 Cue
• 普通点击已有 Hot Cue：跳转到该位置

按住 Shift 操作 Hot Cue 时不会误触 Deck 播放快捷键。

本地数据与隐私

• 歌曲不会提交到本仓库，也不会被上传到 PulseGrid 的外部服务器。
• 上传文件和分析 job 保存在本机 digital-mixer/runtime/。
• 部分界面状态、Cue、评分或标签可能保存在当前浏览器的本地存储中。
• 不同电脑、浏览器或浏览器 Profile 之间不会自动同步 Library。
• 清空浏览器数据、删除 runtime 目录、删除容器数据或重新安装前，请自行确认是否需要保留数据。
• 分享本仓库时，请勿提交你没有权利再分发的音乐文件。

仓库包含与不包含的内容

仓库包含：

• PulseGrid HTML / CSS / JavaScript 前端
• 本地 Node.js 服务
• 项目内 bass-set-maker 分析和 Set 规划实现
• Python 依赖清单和锁文件
• Docker、macOS 启动脚本和自动检查配置

仓库不包含：

• 任何歌曲、采样、Stem 或录音
• 预设 Library、歌单、Crate 或用户评分
• projects/ 中的历史 Set、渲染音频和分析产物
• digital-mixer/runtime/ 中的上传歌曲和 job
• 当前电脑的 .venv、缓存或本机绝对路径环境
• FFmpeg、Rubber Band 等第三方二进制文件

限制与故障排查

页面无法打开

• 确认终端中的服务仍在运行。
• 打开的是 http://127.0.0.1:4173/digital-mixer/，不是直接双击 index.html。
• 如果端口被占用，先停止旧的 PulseGrid 服务或占用 4173 端口的程序。

Analyze failed / FFmpeg 错误

• Docker 模式：重新运行 docker compose up --build，确认构建过程没有失败。
• macOS 模式：重新运行 ./scripts/setup-macos.sh，再启动服务。
• 不要使用从另一台电脑复制来的 .venv。
• 确认音频能被常见播放器正常打开，且格式在支持列表内。

Auto Play is not ready

这通常表示某组 Cue 8 → Cue 5 转场没有通过 transition audit，或 Cue 在校验后被修改。打开对应 Preview，完整试听并按界面提示确认；必要时调整 Cue、替换歌曲、改变曲序或重新审计。系统不会为了强行播放而忽略结构性风险。

没有声音

• 先在页面上点击一次，允许浏览器启动 Web Audio。
• 检查 Deck Play、Channel fader、Crossfader、Master 音量和系统输出设备。
• Chrome / Edge 对 Web Audio 和 AudioWorklet 的支持最完整。

分析或 Set Creation 较慢

首次运行会安装依赖或建立缓存；长音频和大量歌曲也需要更多时间。Docker Desktop 的 CPU / 内存限制过低时，可适当增加资源配额。

GitHub Pages 为什么不能运行

GitHub Pages 只能托管静态文件。PulseGrid 的 Analyze、Set Creation 和 transition audit 需要本地 Node.js API、Python 和音频工具，因此不能只把 index.html 部署到 GitHub Pages。GitHub 在这里用于保存和分发代码；应用仍需在用户电脑上启动，或部署到具有完整后端和持久存储的服务器。

当前技术边界

• Heuristic 结构识别可能在半拍 BPM、复杂 live intro、弱拍或模糊 Drop 中出现偏差，低置信度结果需要人工检查。
• 浏览器内 Key Shift 和实时 DSP 适合本地编排与排练，但不等同于商业 DJ 硬件或专用音频引擎。
• 目标 Set 时长是软目标；素材不足时，以安全的结构和转场为优先。
• 公开或商业分发前，请检查你所使用的 FFmpeg、Rubber Band 和 Python 依赖版本对应的许可证义务，详见 THIRD_PARTY_NOTICES.md。

---

English

Overview

PulseGrid is an open-source, local, AI-native dual-deck DJ workstation. It combines the waveforms, Sync, cues, loops, EQ, FX, and hands-on controls expected from professional DJ software with an intelligent workflow that reaches from individual-track analysis to a complete automated performance.

Upload your own tracks to analyze BPM, key, beatgrid, energy, double drops, waveform, and musical structure. Then describe the duration, style, and energy arc you want in natural language. PulseGrid uses the analyzed Library to plan the order, a transition-specific Cue 8 → Cue 5 handoff for each neighboring pair, and the EQ / Filter / FX / Crossfader automation required to perform it.

PulseGrid is local-first: the web app, analysis service, audio files, and analysis results run and remain on your computer. Your music does not need to be sent to a third-party cloud service.

Why this is more than Auto Mix

Typical Auto Mix	PulseGrid
Fades out near the end and fades in near the beginning	Selects transition points from phrases, sections, drops, and energy
Keeps handoff decisions inside a black box	Shows Cue 8 → Cue 5 on the decks and Tracklist for listening and editing
Reuses a generic fade curve	Plans EQ, Filter, FX, and Crossfader moves for each neighboring pair
Plays an ordered playlist	Creates a full set and energy narrative from a natural-language brief
Asks you to trust the result	Provides Preview and transition audit before Auto Play, with manual takeover at any time

The goal is not to replace the DJ. It is to turn the slow work of analysis, cue discovery, transition testing, and set planning into a transparent collaboration that the DJ can inspect, correct, and perform.

Product features

Dual decks and core mixing

• Deck A / Deck B layout
• Overview and scrolling zoomed waveforms
• BPM detection, Sync, beat phase, and Master Deck
• Beatgrid controls, Tap BPM, grid nudge, BPM ×2 / ÷2
• Key detection, Camelot display, Key Sync, and Key Shift
• Tempo / pitch fader, Pitch Bend, and Master Tempo
• Three-band EQ, bipolar Filter, channel faders, equal-power Crossfader, and master limiter
• Jog / scratch, seek, Slip, and Quantize

Cues, loops, and beat controls

• Up to eight Hot Cues per track
• Memory Cue
• Auto Loop and Manual Loop
• Beat Jump
• User-editable and removable cue points

The track-analysis stage creates structural cues for manual DJing. Cue 5 and Cue 8 are not forced to the beginning and end of a track. They are created during Set Creation for a specific neighboring track and transition:

• Cue 5 / AUTO IN: where this track enters from the previous track
• Cue 8 / AUTO OUT: where this track exits into the next track
• The first track in a set does not require Cue 5
• The final track in a set does not require Cue 8

FX and audio processing

• Echo, Reverb, Flanger, Gate, and Filter FX
• Beat-division / tempo-aware parameters
• Independently collapsible FX racks for Deck A and Deck B
• Automated High / Mid / Low, Filter, Echo, and Crossfader moves during transitions
• Browser master-output recording

Library

• Local audio upload
• Search, sorting, ratings, and tags
• Crates, Smart Lists, and analysis status
• BPM, key, waveform, energy, and structure pre-analysis
• An empty Library by default, with no fictional tracks or playlists

Set Creation and Auto Play

1. Upload and Analyze tracks in the Library.
2. Open CREATE / SET CREATION and describe the preferred duration, style, energy curve, or ending.
3. bass-set-maker uses the completed track analyses to plan track order, playback rate, transition type, Cue 8 → Cue 5 handoffs, and a transition audit.
4. The Tracklist shows deck assignment, cues, BPM, key, transition details, and EQ / Filter / FX automation.
5. Use CHECK A8→B5 / Preview between two tracks to load them into Deck A and B and hear the real transition.
6. Once the set is ready, AUTO PLAY rotates tracks through A → B → A, loads and starts them at their planned cues, and performs the planned control changes.
7. Individual tracks can be removed or replaced, and the full Tracklist can be cleared. Affected transitions are recalculated after edits.

If you edit Cue 5 or Cue 8, subsequent review and Auto Play use your updated position. Changing cues or taking control of a deck during playback may return the system to manual mode so automation does not continue from an unknown state.

Download and installation

Option A: Docker (recommended)

Docker provides a consistent environment for Node.js, Python, and system audio dependencies. It is the easiest option when using PulseGrid on another Mac, Windows, or Linux computer.

Install first:

• Git if you plan to clone the repository
• Docker Desktop or a compatible Docker Engine

Download from GitHub:

git clone https://github.com/ysy-ym/pulsegrid.git
cd pulsegrid

Alternatively, choose Code → Download ZIP on the repository page, extract the archive, and open the pulsegrid directory.

Start PulseGrid:

./scripts/start-docker.sh

On Windows PowerShell, you can run:

.\scripts\start-windows.ps1

Or run Docker Compose directly:

docker compose up --build

When the build is ready, open:

http://127.0.0.1:4173/digital-mixer/

Press Ctrl+C in the running terminal to stop the service. Later starts can use the same command; Docker will reuse previously built image layers when possible.

Docker stores local uploads and analysis jobs in a named pulsegrid-runtime volume. A normal docker compose down preserves this data. Explicitly deleting the volume—for example with docker compose down -v—clears it.

Option B: native macOS installation

Native mode is useful when you want to use the host Python and FFmpeg installations, or when developing and debugging PulseGrid.

Requirements:

• macOS
• Homebrew
• Internet access to download open-source dependencies

Enter the repository and run the setup script once:

./scripts/setup-macos.sh

After setup, start the service with:

./scripts/start-macos.command

You may also double-click scripts/start-macos.command in Finder. Then open:

http://127.0.0.1:4173/digital-mixer/

The setup script creates an isolated Python environment and installs the required dependencies for this repository. Do not copy a .venv from another computer; virtual environments commonly contain operating-system, CPU, and absolute-path-specific files.

Option C: GitHub Releases

If the repository has published a Release:

1. Open Releases on the repository page.
2. Select the latest version.
3. Download the published ZIP or GitHub's Source code (zip) archive.
4. Extract it and follow either the Docker or native macOS instructions above.

A Release package still contains no music, Library, or other user data. The Library is empty on first launch.

First run

1. Start the service and open PulseGrid in Chrome or Edge.
2. Click UPLOAD / ADD MUSIC and select local audio you are authorized to use.
3. Wait for Analyze to finish. It creates BPM, key, beatgrid, waveform, energy, structure, and manual-performance cues.
4. Load a track into Deck A or B for manual mixing.
5. To create an automatic arrangement, click CREATE, enter the set request, and generate the Tracklist.
6. Preview adjacent transitions before starting AUTO PLAY.

Common supported formats include WAV, MP3, AIFF, M4A, AAC, FLAC, OGG, and Opus. The local upload limit is 600 MB per file.

Keyboard and cue controls

• Tap Left Shift by itself: play / pause Deck A
• Tap Right Shift by itself: play / pause Deck B
• Shift + click a Hot Cue: overwrite it at the current playhead
• Right-click a Hot Cue: clear it
• Click an existing Hot Cue normally: jump to it

Holding Shift while editing a Hot Cue does not trigger the deck playback shortcut.

Local data and privacy

• Music is not committed to this repository or uploaded to an external PulseGrid server.
• Uploaded files and analysis jobs are stored locally under digital-mixer/runtime/.
• Some UI state, cues, ratings, or tags may be stored in the current browser's local storage.
• Libraries do not automatically sync across computers, browsers, or browser profiles.
• Before clearing browser data, removing runtime data, deleting container data, or reinstalling, decide whether you need to preserve anything locally.
• Do not commit or redistribute music unless you have the rights to do so.

What the repository includes

• The PulseGrid HTML / CSS / JavaScript frontend
• The local Node.js service
• The project-local bass-set-maker analysis and set-planning implementation
• Python dependency declarations and lockfile
• Docker and macOS setup/start scripts, plus automated checks

What the repository does not include

• Songs, samples, stems, or recordings
• A prebuilt Library, playlists, crates, or user ratings
• Historical sets, rendered audio, or analysis artifacts from projects/
• Uploaded tracks and jobs from digital-mixer/runtime/
• The current computer's .venv, caches, or absolute-path environment
• Third-party FFmpeg or Rubber Band binaries

Limitations and troubleshooting

The page does not open

• Confirm that the service is still running in the terminal.
• Open http://127.0.0.1:4173/digital-mixer/; do not open index.html directly.
• If the port is busy, stop an older PulseGrid process or the other application using port 4173.

Analyze failed / FFmpeg error

• Docker: run docker compose up --build again and confirm that the image build completes.
• Native macOS: rerun ./scripts/setup-macos.sh, then start the service again.
• Do not reuse a .venv copied from another computer.
• Confirm that a normal media player can open the source audio and that the format is supported.

Auto Play is not ready

This usually means that a Cue 8 → Cue 5 transition did not pass its transition audit, or that a cue changed after review. Open the relevant Preview, listen to the full transition, and follow the review prompt. If needed, move a cue, replace a track, change the order, or retry the audit. PulseGrid does not ignore structural failures merely to force Auto Play to begin.

There is no sound

• Click once inside the page so the browser can start Web Audio.
• Check Deck Play, channel faders, Crossfader, Master level, and the operating-system output device.
• Chrome and Edge currently provide the most complete Web Audio and AudioWorklet support.

Analysis or Set Creation is slow

The first run may install dependencies or build caches. Long tracks and large batches also take more time. If Docker Desktop has a very low CPU or memory limit, increase its resource allocation.

Why GitHub Pages cannot run PulseGrid

GitHub Pages serves static files only. Analyze, Set Creation, and transition audit require the local Node.js API, Python, and audio tools, so deploying only index.html to Pages is insufficient. GitHub is used to store and distribute the project; the application still runs on the user's computer, unless you separately deploy a full backend with persistent storage.

Current technical boundaries

• Heuristic structure detection can be inaccurate with half-time BPM, complex live intros, weak downbeats, or ambiguous drops; review low-confidence results manually.
• Browser-based Key Shift and real-time DSP are useful for local set planning and rehearsal, but are not equivalent to dedicated commercial DJ hardware or audio engines.
• Target set duration is a soft goal. PulseGrid prioritizes safer structure and transitions when the available material is insufficient.
• Before public or commercial distribution, review the license obligations of the exact FFmpeg, Rubber Band, and Python dependency versions you use. See THIRD_PARTY_NOTICES.md.

License

PulseGrid's original source code is released under the MIT License, unless a file states otherwise. Third-party components remain subject to their own licenses.