vizcore 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 824691790c88752d418cb0e2ca49a39a15e76926cc8025ac51403b3ba2797f1c
+  data.tar.gz: bc3ed3cd8282e51dbc21e175b6f8aa76ea7d9c7a7d1ccdfb6e2fc5dfa5b42374
+SHA512:
+  metadata.gz: 4786e0f33292f0598c19c106d544f25775a721e76173bee09fd45f8917a8c148f10a30756c948753165937917f4e5e44c97295e12882243aba6605c07cd3746b
+  data.tar.gz: 99cbff89caa54d6bbfedfd116754827eb3d09267d931839a4fae2dff65b3ae65ca5efeb8b43f5652c3f35e591aa4a50c37967f1942af66594ea5a3528167bb42

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# Vizcore [![Gem Version](https://badge.fury.io/rb/vizcore.svg)](https://badge.fury.io/rb/vizcore) [![CI](https://github.com/ydah/vizcore/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/vizcore/actions/workflows/main.yml)
+
+Vizcore is a Ruby gem for building audio-reactive visuals with a Ruby DSL. Define scenes in pure Ruby, stream frames to the browser over WebSocket, and react to audio, beat, and MIDI in real time.
+
+## Installation
+
+```bash
+gem install vizcore
+```
+
+Or add to your Gemfile:
+
+```bash
+bundle add vizcore
+```
+
+**System dependencies:**
+
+macOS:
+```bash
+brew install portaudio ffmpeg   # ffmpeg only needed for MP3/FLAC input
+brew install fftw               # optional: faster FFT
+```
+
+Ubuntu/Debian:
+```bash
+sudo apt install -y libportaudio2 libportaudio-dev ffmpeg
+sudo apt install -y libfftw3-dev   # optional: faster FFT
+```
+
+## Quick Start
+
+```bash
+vizcore start examples/basic.rb
+```
+
+Then open `http://127.0.0.1:4567`.
+
+For full setup, device listing, and troubleshooting, see [GETTING_STARTED.md](docs/GETTING_STARTED.md).
+
+## Scene DSL
+
+Scenes are written in plain Ruby. Layers map audio analysis values to visual parameters:
+
+```ruby
+Vizcore.define do
+  scene :intro do
+    layer :wireframe do
+      type :wireframe_cube
+      map amplitude => :rotation_speed
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+    end
+  end
+
+  scene :drop do
+    layer :particles do
+      type :particle_field
+      count 3600
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+    end
+
+    layer :title do
+      type :text
+      content "DROP"
+      font_size 96
+      map beat? => :flash
+    end
+  end
+
+  transition from: :intro, to: :drop do
+    trigger { beat_count >= 64 }
+    effect :crossfade, duration: 1.4
+  end
+end
+```
+
+### Custom GLSL Shaders
+
+```ruby
+layer :wave_shader do
+  type :shader
+  glsl "shaders/custom_wave.frag"
+  map amplitude => :param_intensity
+  map frequency_band(:low) => :param_bass
+  map beat? => :param_flash
+end
+```
+
+### MIDI Scene Switching
+
+```ruby
+Vizcore.define do
+  midi :controller, device: :default
+
+  scene :warmup do
+    layer :grid do
+      shader :neon_grid
+      map frequency_band(:mid) => :intensity
+    end
+  end
+
+  midi_map note: 36 do
+    switch_scene :impact
+  end
+
+  midi_map cc: 1 do |value|
+    set :global_intensity, value / 127.0
+  end
+end
+```
+
+## CLI
+
+```bash
+vizcore start SCENE_FILE [--host 127.0.0.1] [--port 4567] [--audio-source mic|file|dummy] [--audio-file PATH]
+vizcore new PROJECT_NAME
+vizcore devices [audio|midi]
+```
+
+### Audio Sources
+
+| Source | Description |
+|--------|-------------|
+| `mic` | Live microphone input (default) |
+| `file` | File playback — `.wav` directly, `.mp3`/`.flac` via `ffmpeg` |
+| `dummy` | Silent source for layout testing |
+
+```bash
+# Microphone
+vizcore start scene.rb --audio-source mic
+
+# WAV file
+vizcore start scene.rb --audio-source file --audio-file track.wav
+
+# MP3/FLAC (requires ffmpeg)
+vizcore start scene.rb --audio-source file --audio-file set.mp3
+```
+
+When using file source, the HUD exposes **Play Audio** / **Pause Audio** controls and shows BPM, Beat, and Beat Count.
+
+## Requirements
+
+- Ruby `>= 3.2`
+- `portaudio` for microphone input
+- `ffmpeg` on `PATH` when using `.mp3` or `.flac` file input
+- `fftw3` (optional) — Vizcore falls back to pure-Ruby FFT automatically when unavailable
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `examples/basic.rb` | Single wireframe cube layer |
+| `examples/intro_drop.rb` | Beat-triggered scene transition |
+| `examples/file_audio_demo.rb` | File audio source walkthrough |
+| `examples/complex_audio_showcase.rb` | Dense multi-layer showcase |
+| `examples/midi_scene_switch.rb` | MIDI-driven scene switching |
+| `examples/custom_shader.rb` | Custom GLSL shader with audio mapping |
+
+## Development
+
+```bash
+bundle exec rspec
+```
+
+
+## License
+
+MIT

data/docs/GETTING_STARTED.md

@@ -0,0 +1,105 @@
+# Getting Started
+
+This guide covers local setup and first-run commands for `vizcore`.
+
+## 1. Prerequisites
+
+### macOS (Homebrew)
+
+```bash
+brew install portaudio ffmpeg
+# optional (recommended for faster FFT): brew install fftw
+```
+
+### Ubuntu/Debian
+
+```bash
+sudo apt update
+sudo apt install -y libportaudio2 libportaudio-dev ffmpeg
+# optional (recommended for faster FFT): sudo apt install -y libfftw3-dev
+```
+
+### Ruby
+
+- Ruby `3.2+`
+- Bundler
+
+## 2. Install and Boot
+
+### Run from this repository
+
+```bash
+bundle install
+bundle exec ruby -Ilib exe/vizcore start examples/basic.rb
+```
+
+Open `http://127.0.0.1:4567`.
+
+### Project scaffold
+
+```bash
+bundle exec ruby -Ilib exe/vizcore new my_show
+cd my_show
+vizcore start scenes/basic.rb
+```
+
+## 3. Audio Source Selection
+
+### Microphone input
+
+```bash
+vizcore start examples/basic.rb --audio-source mic
+```
+
+### File input (WAV)
+
+```bash
+vizcore start examples/basic.rb --audio-source file --audio-file spec/fixtures/audio/kick_120bpm.wav
+```
+
+### File input (MP3/FLAC via ffmpeg)
+
+```bash
+vizcore start examples/basic.rb --audio-source file --audio-file path/to/set.mp3
+```
+
+### Dummy source fallback
+
+```bash
+vizcore start examples/basic.rb --audio-source dummy
+```
+
+## 4. Device Discovery
+
+```bash
+vizcore devices audio
+vizcore devices midi
+```
+
+## 5. Useful Example Scenes
+
+```bash
+vizcore start examples/complex_audio_showcase.rb --audio-source file --audio-file examples/assets/complex_demo_loop.wav
+vizcore start examples/file_audio_demo.rb --audio-source file --audio-file spec/fixtures/audio/kick_120bpm.wav
+vizcore start examples/intro_drop.rb --audio-source dummy
+vizcore start examples/midi_scene_switch.rb --audio-source dummy
+vizcore start examples/custom_shader.rb --audio-source dummy
+```
+
+`intro_drop` falls back to a time-based transition after about 6 seconds when beats are not detected. For beat-synced scene changes, use rhythmic file input:
+
+```bash
+vizcore start examples/intro_drop.rb --audio-source file --audio-file spec/fixtures/audio/kick_120bpm.wav
+```
+
+File source mode exposes `Play Audio` / `Pause Audio` in the HUD and streams the same file to the browser (`/audio-file`). If autoplay is blocked, click `Play Audio` once.
+`examples/complex_audio_showcase.rb` uses the bundled `examples/assets/complex_demo_loop.wav` loop for a denser audio-reactive demo.
+
+The HUD displays `BPM`, `Beat`, and `Beat Count`, which helps confirm synchronization while pausing or seeking playback.
+
+## 6. Troubleshooting
+
+- `Audio file not found`: check `--audio-file` path.
+- `.mp3` / `.flac` fails: confirm `ffmpeg -version` works.
+- No mic signal on macOS: allow microphone permission for the Ruby process/terminal app.
+- Web page does not update: check terminal logs and browser devtools console.

data/examples/basic.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+Vizcore.define do
+  scene :basic do
+    layer :wireframe_cube do
+      type :wireframe_cube
+    end
+  end
+end

data/examples/complex_audio_showcase.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+# Recommended audio file for this scene:
+#   examples/assets/complex_demo_loop.wav
+Vizcore.define do
+  scene :build do
+    layer :rings do
+      shader :spectrum_rings
+      opacity 0.88
+      effect :feedback
+      effect_intensity 0.08
+      map frequency_band(:low) => :rotation_speed
+    end
+
+    layer :grid do
+      shader :neon_grid
+      opacity 0.28
+      blend :add
+      vj_effect :mirror
+      effect_intensity 0.18
+      map frequency_band(:high) => :effect_intensity
+    end
+
+    layer :particles do
+      type :particle_field
+      count 3800
+      blend :add
+      opacity 0.74
+      size 2.2
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      blend :add
+      opacity 0.9
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+      map frequency_band(:mid) => :rotation_speed
+    end
+
+    layer :title do
+      type :text
+      content "SYNCED SHOWCASE"
+      font_size 56
+      color "#e8f8ff"
+      glow_strength 0.12
+      map beat? => :glow_strength
+    end
+  end
+
+  scene :lift do
+    layer :background do
+      shader :bass_tunnel
+      opacity 0.94
+      effect :feedback
+      effect_intensity 0.16
+      map frequency_band(:low) => :rotation_speed
+      map frequency_band(:mid) => :effect_intensity
+    end
+
+    layer :grid do
+      shader :neon_grid
+      opacity 0.34
+      blend :add
+      vj_effect :color_shift
+      effect_intensity 0.22
+      map frequency_band(:high) => :effect_intensity
+    end
+
+    layer :particles do
+      type :particle_field
+      count 6800
+      blend :add
+      size 3.6
+      effect :chromatic
+      effect_intensity 0.18
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+      map frequency_band(:high) => :effect_intensity
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      blend :add
+      opacity 0.78
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+      map frequency_band(:low) => :rotation_speed
+    end
+
+    layer :title do
+      type :text
+      content "LIFT"
+      font_size 72
+      color "#eefbff"
+      glow_strength 0.16
+      map beat? => :glow_strength
+    end
+  end
+
+  scene :drop do
+    layer :bg do
+      shader :kaleidoscope
+      opacity 0.98
+      effect :glitch
+      effect_intensity 0.65
+      map frequency_band(:low) => :rotation_speed
+      map frequency_band(:high) => :effect_intensity
+    end
+
+    layer :flash do
+      shader :glitch_flash
+      opacity 0.8
+      blend :add
+      map amplitude => :param_intensity
+      map frequency_band(:high) => :param_flash
+    end
+
+    layer :storm do
+      type :particle_field
+      count 9000
+      blend :add
+      size 4.8
+      vj_effect :pixelate
+      effect_intensity 0.55
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+      map frequency_band(:mid) => :effect_intensity
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      blend :add
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+      map frequency_band(:low) => :rotation_speed
+    end
+
+    layer :title do
+      type :text
+      content "DROP"
+      font_size 94
+      color "#f2fdff"
+      glow_strength 0.25
+      map beat? => :glow_strength
+    end
+  end
+
+  scene :afterglow do
+    layer :bars do
+      shader :audio_bars
+      opacity 1.0
+      effect :feedback
+      effect_intensity 0.05
+      bar_count 28
+      floor_glow 0.12
+      map frequency_band(:low) => :effect_intensity
+    end
+
+    layer :dust do
+      type :particle_field
+      count 2200
+      blend :add
+      opacity 0.38
+      size 1.9
+      map amplitude => :speed
+      map frequency_band(:high) => :size
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      blend :add
+      opacity 0.24
+      map fft_spectrum => :deform
+      map frequency_band(:mid) => :color_shift
+      map amplitude => :rotation_speed
+    end
+
+    layer :title do
+      type :text
+      content "AFTERGLOW"
+      font_size 52
+      color "#edf5ff"
+      glow_strength 0.08
+      map beat? => :glow_strength
+    end
+  end
+
+  scene :breakdown do
+    layer :background do
+      shader :neon_grid
+      opacity 0.3
+      effect :feedback
+      effect_intensity 0.05
+      rotation_speed 0.18
+      map frequency_band(:mid) => :effect_intensity
+    end
+
+    layer :rings do
+      shader :spectrum_rings
+      opacity 0.26
+      effect :feedback
+      effect_intensity 0.06
+      map frequency_band(:low) => :rotation_speed
+    end
+
+    layer :dust do
+      type :particle_field
+      count 1800
+      blend :add
+      opacity 0.46
+      size 1.8
+      map amplitude => :speed
+      map frequency_band(:high) => :size
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      opacity 0.22
+      map fft_spectrum => :deform
+      map frequency_band(:mid) => :color_shift
+      map amplitude => :rotation_speed
+    end
+
+    layer :title do
+      type :text
+      content "BREAKDOWN"
+      font_size 46
+      color "#e6f0ff"
+      glow_strength 0.06
+      map beat? => :glow_strength
+    end
+  end
+
+  transition from: :build, to: :lift do
+    trigger { beat_count >= 24 || frame_count >= 900 }
+    effect :crossfade, duration: 0.9
+  end
+
+  transition from: :lift, to: :drop do
+    trigger { beat_count >= 16 || frame_count >= 540 }
+    effect :crossfade, duration: 1.0
+  end
+
+  transition from: :drop, to: :afterglow do
+    trigger { beat_count >= 24 || frame_count >= 900 }
+    effect :crossfade, duration: 1.1
+  end
+
+  transition from: :afterglow, to: :breakdown do
+    trigger { beat_count >= 12 || frame_count >= 420 }
+    effect :crossfade, duration: 1.0
+  end
+
+  transition from: :breakdown, to: :build do
+    trigger { beat_count >= 16 || frame_count >= 720 }
+    effect :crossfade, duration: 1.2
+  end
+end

data/examples/custom_shader.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Vizcore.define do
+  scene :shader_art do
+    layer :wave_shader do
+      type :shader
+      glsl "shaders/custom_wave.frag"
+      map amplitude => :param_intensity
+      map frequency_band(:low) => :param_bass
+      map beat? => :param_flash
+    end
+
+    layer :title do
+      type :text
+      content "VIZCORE"
+      font_size 72
+      glow_strength 0.0
+      color "#f8fbff"
+    end
+  end
+end

data/examples/file_audio_demo.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+Vizcore.define do
+  scene :groove do
+    layer :background do
+      shader :bass_tunnel
+      opacity 1.0
+      effect :feedback
+      effect_intensity 0.72
+      rotation_speed 1.4
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      blend :add
+      map fft_spectrum => :deform
+      map frequency_band(:mid) => :color_shift
+      map frequency_band(:low) => :rotation_speed
+    end
+
+    layer :particles do
+      type :particle_field
+      count 4200
+      blend :add
+      size 3.8
+      effect :chromatic
+      effect_intensity 0.7
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+      map frequency_band(:high) => :effect_intensity
+    end
+
+    layer :title do
+      type :text
+      content "FILE AUDIO DEMO"
+      font_size 64
+      color "#f2f7ff"
+      glow_strength 0.18
+      map beat? => :glow_strength
+    end
+  end
+
+  scene :drop do
+    layer :background do
+      shader :kaleidoscope
+      opacity 0.95
+      effect :glitch
+      effect_intensity 0.86
+      rotation_speed 2.4
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      blend :add
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+      map frequency_band(:mid) => :rotation_speed
+    end
+
+    layer :title do
+      type :text
+      content "DROP"
+      font_size 92
+      color "#eaffff"
+      glow_strength 0.32
+      map beat? => :glow_strength
+    end
+  end
+
+  transition from: :groove, to: :drop do
+    trigger { beat_count >= 32 || frame_count >= 720 }
+    effect :crossfade, duration: 1.0
+  end
+end

data/examples/intro_drop.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+Vizcore.define do
+  scene :intro do
+    layer :background do
+      shader :neon_grid
+      opacity 0.82
+    end
+
+    layer :wireframe do
+      type :wireframe_cube
+      map amplitude => :rotation_speed
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+    end
+  end
+
+  scene :drop do
+    layer :particles do
+      type :particle_field
+      count 3600
+      map amplitude => :speed
+      map frequency_band(:low) => :size
+    end
+
+    layer :title do
+      type :text
+      content "DROP"
+      font_size 96
+      map beat? => :flash
+    end
+  end
+
+  transition from: :intro, to: :drop do
+    trigger { beat_count >= 64 || frame_count >= 360 }
+    effect :crossfade, duration: 1.4
+  end
+end