dokidoki

Control your interactive device from the terminal.

A Node.js CLI tool for controlling BLE devices with timeline-based playback, featuring background daemon for persistent connections and audio synchronization.

Features

• 🎵 Timeline Playback - Play device actions synchronized with audio files
• 🔄 Background Daemon - Persistent BLE connection, playback continues after CLI exits
• ⏸️ Play/Pause/Resume - Full playback control with automatic device stop
• 🎮 Direct Control - Set linear, rotary, vibration, and suction values directly
• 🔌 BLE Management - Scan, connect, disconnect devices
• 🎧 Audio Formats - MP3, AAC/M4A, WAV, FLAC, OGG, AIFF

Installation

npm install -g @tryjoy/dokidoki

Quick Start

# Start the background daemon
doki start

# Scan for devices
doki scan

# Connect to device
doki connect DK-META2

# Play timeline with audio (runs in background)
doki player play song.mp3 timeline.json

# Control playback
doki player pause    # Pause and stop device
doki player resume   # Resume playback

# Stop all device actions immediately
doki action pause

# Check status
doki status

# Stop daemon
doki stop

Commands

Daemon Management

doki start              # Start background daemon
doki stop               # Stop background daemon
doki status             # Check daemon and connection status

Device Connection

doki scan               # Scan for BLE devices
doki connect [name]     # Connect to device (default: DK-META2)
doki disconnect         # Disconnect from device

Timeline Playback

doki player play [audio.mp3] <timeline.json>   # Play timeline
doki player pause                               # Pause (stops device)
doki player resume                              # Resume playback

Direct Device Control

doki action linear 50      # Set linear to 50%
doki action rotary -- -30  # Set rotary to -30 (reverse)
doki action vibration 80   # Set vibration to 80%
doki action suction 20     # Trigger suction at 20% (TF-PTPRO: one-shot, not continuous)
doki action pause          # Stop all device actions immediately

Timeline Format

Timeline files are JSON files that define device actions at specific timestamps:

{
  "duration": 180.5,
  "actions": [
    {"timestamp": 0.0, "type": "VIBRATION", "value": 50},
    {"timestamp": 5.5, "type": "LINEAR", "value": 30},
    {"timestamp": 10.0, "type": "ROTARY", "value": -50},
    {"timestamp": 15.0, "type": "LINEAR", "value": 80},
    {"timestamp": 20.0, "type": "VIBRATION", "value": 0}
  ]
}

Action Types

| Type | Value Range | Description | |------|-------------|-------------| | LINEAR | 0-100 | Linear/stroke movement intensity | | ROTARY | -100 to 100 | Rotation speed (negative = reverse) | | VIBRATION | 0-100 | Vibration intensity |

Playback Behavior

• Audio ends → Device automatically stops (all values set to 0)
• Timeline ends → Device automatically stops
• Pause → Device stops immediately, timeline position preserved
• Resume → Audio seeks to timeline position, playback continues
• Action pause → Device stops immediately, playback continues

Requirements

• Node.js 18+
• For audio playback: ffplay (Linux/Windows) or afplay (macOS)

Development

npm install         # Install dependencies
npm start           # Run CLI (uses dist/ artefacts)

# Rebuild after editing source
npm run build:dev   # Dev build: no minify/obfuscation, inline sourcemap, ~sub-second
npm run build       # Release build: minify + obfuscate
npm run restart     # stop + build:dev + start — use this after editing daemon-side code

Using the doki command locally

Without a global install, doki xxx yields command not found. Two options:

# Option A: call the binary directly
node bin/doki.js <command>

# Option B: npm link once — exposes `doki` globally, pointing at this repo
npm link
which doki          # should point at this repo's bin/doki.js
doki <command>

# Remove the symlink when you're done
npm unlink -g @tryjoy/dokidoki

The symlink from npm link just points at bin/doki.js, so subsequent rebuilds don't need a re-link.

Note: the daemon (started by doki start / doki connect) is a separate process running whatever dist/doki.js contained when it launched. Later rebuilds don't affect an already-running daemon.

After editing daemon-side code (daemon.js, bleController.js, profiles.js, etc.) just run:

npm run restart

Edits limited to CLI parsing (cli/index.js, commands like doki profiles) don't require a daemon restart — npm run build:dev is enough.

Logs

Daemon logs are written to /tmp/dokidoki.log

# View logs
tail -f /tmp/dokidoki.log

Languages / 语言 / 言語

• English (Current)
• 中文
• 日本語

License

MIT