vizcore 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 824691790c88752d418cb0e2ca49a39a15e76926cc8025ac51403b3ba2797f1c
-  data.tar.gz: bc3ed3cd8282e51dbc21e175b6f8aa76ea7d9c7a7d1ccdfb6e2fc5dfa5b42374
+  metadata.gz: c750ff1ca41db0024074232a588262d5220e4063cdb057421c25465b1de102eb
+  data.tar.gz: 3123d34ed03e497dde1530bc41ade0c5177c519072713817429d5e8187d97059
 SHA512:
-  metadata.gz: 4786e0f33292f0598c19c106d544f25775a721e76173bee09fd45f8917a8c148f10a30756c948753165937917f4e5e44c97295e12882243aba6605c07cd3746b
-  data.tar.gz: 99cbff89caa54d6bbfedfd116754827eb3d09267d931839a4fae2dff65b3ae65ca5efeb8b43f5652c3f35e591aa4a50c37967f1942af66594ea5a3528167bb42
+  metadata.gz: ce9f65e426497957526ce5e73cd6eb4cfb0f5981fb1f3151cb12a39201d4d0bb3b5dad0b2563e5fe7220c2357e94e5efcb7956e49efd8167f836cbf89d22b875
+  data.tar.gz: b6ba9c3755a3ca4ba4e1fb4f163d55e0275c7ba513d8d39891893528238e39fe553cc020c14538bfac49e1a1f355e161e899904c1c0f57e77aa47e027444c774

data/README.md

@@ -1,170 +1,123 @@
 # 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.
+Vizcore is a Ruby gem for audio-reactive VJ visuals. Define scenes in Ruby, stream them to a browser renderer, and map audio analysis, beats, MIDI, OSC, and live controls to visual parameters.
 
-## Installation
+<p align="center">
+  <img src="docs/assets/vizcore-demo.gif" width="640" alt="Animated Vizcore demo where detected beats expand concentric rings" />
+</p>
 
-```bash
-gem install vizcore
-```
+## Install
 
-Or add to your Gemfile:
+Requirements:
 
-```bash
-bundle add vizcore
-```
-
-**System dependencies:**
+- Ruby `>= 3.2`
+- PortAudio for microphone input
+- ffmpeg for MP3/FLAC input and MP4 output
+- fftw3 optional for faster FFT analysis
 
-macOS:
 ```bash
-brew install portaudio ffmpeg   # ffmpeg only needed for MP3/FLAC input
-brew install fftw               # optional: faster FFT
+# macOS
+brew install portaudio ffmpeg
+brew install fftw # optional
+
+# Ubuntu / Debian
+sudo apt install -y libportaudio2 libportaudio-dev ffmpeg
+sudo apt install -y libfftw3-dev # optional
 ```
 
-Ubuntu/Debian:
 ```bash
-sudo apt install -y libportaudio2 libportaudio-dev ffmpeg
-sudo apt install -y libfftw3-dev   # optional: faster FFT
+gem install vizcore
+# or
+bundle add vizcore
 ```
 
 ## Quick Start
 
 ```bash
-vizcore start examples/basic.rb
+vizcore doctor
+vizcore demo
 ```
 
-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
+Open `http://127.0.0.1:4567`.
 
-    layer :title do
-      type :text
-      content "DROP"
-      font_size 96
-      map beat? => :flash
-    end
-  end
+To run a scene file directly:
 
-  transition from: :intro, to: :drop do
-    trigger { beat_count >= 64 }
-    effect :crossfade, duration: 1.4
-  end
-end
+```bash
+vizcore start examples/basic.rb
+vizcore start examples/vj_techno_warehouse.rb --audio-source file --audio-file examples/assets/complex_demo_loop.wav
 ```
 
-### 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
-```
+## Minimal Scene
 
-### MIDI Scene Switching
+Scenes are plain Ruby files:
 
 ```ruby
 Vizcore.define do
-  midi :controller, device: :default
-
-  scene :warmup do
-    layer :grid do
-      shader :neon_grid
-      map frequency_band(:mid) => :intensity
+  scene :readme_demo do
+    layer :beat_rings do
+      palette "#24f6ff", "#ff2bbd", "#caff2e"
+
+      circle count: 4 do
+        radius 92
+        stroke 3
+        map beat_pulse,
+            to: :radius,
+            gain: 160.0,
+            min: 56,
+            max: 164,
+            attack: 1.0,
+            release: 0.2
+      end
     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
+Run it with:
 
 ```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]
+vizcore start scene.rb
 ```
 
-### Audio Sources
-
-| Source | Description |
-|--------|-------------|
-| `mic` | Live microphone input (default) |
-| `file` | File playback — `.wav` directly, `.mp3`/`.flac` via `ffmpeg` |
-| `dummy` | Silent source for layout testing |
+## Useful Commands
 
 ```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
+vizcore start SCENE_FILE
+vizcore start --manifest vizcore.yml
+vizcore gallery
+vizcore validate SCENE_FILE
+vizcore devices audio
+vizcore devices midi
+vizcore snapshot SCENE_FILE --out screenshot.png
 ```
 
-When using file source, the HUD exposes **Play Audio** / **Pause Audio** controls and shows BPM, Beat, and Beat Count.
+Use `vizcore help` for the full CLI.
 
-## Requirements
+Browser routes:
 
-- 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
+- `/` visual output with operator controls
+- `/projector` clean projection output
+- `/control` separate operator panel
 
-## Examples
+## Documentation
 
-| 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 |
+- Project site: <https://ydah.github.io/vizcore/>
+- Examples: [examples/README.md](examples/README.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Runtime layer reference: `vizcore layers`
+- Ruby DSL reference: `vizcore dsl-docs`
+- Shader uniform reference: `vizcore shader-docs`
 
 ## Development
 
 ```bash
+bundle install
+npm install --prefix frontend
 bundle exec rspec
+npm --prefix frontend test
+bundle exec rake release:verify
 ```
 
-
 ## License
 
 MIT

data/docs/assets/playground-worker.js

@@ -0,0 +1,373 @@
+import { DefaultRubyVM } from "https://cdn.jsdelivr.net/npm/@ruby/wasm-wasi@2.9.4/dist/browser/+esm";
+
+const RUBY_WASM_URL = "https://cdn.jsdelivr.net/npm/@ruby/3.4-wasm-wasi@2.9.4/dist/ruby+stdlib.wasm";
+
+const DSL_RUNTIME = `
+require "base64"
+require "json"
+require "js"
+
+module VizcorePlayground
+  class Source
+    attr_reader :kind, :name
+
+    def initialize(kind, name = nil)
+      @kind = kind.to_s
+      @name = name&.to_s
+    end
+
+    def to_h
+      output = { "source" => kind }
+      output["name"] = name if name
+      output
+    end
+  end
+
+  module Normalizer
+    module_function
+
+    def value(input)
+      case input
+      when Source
+        input.to_h
+      when Symbol
+        input.to_s
+      when Range
+        [input.begin, input.end]
+      when Array
+        input.map { |entry| value(entry) }
+      when Hash
+        input.each_with_object({}) { |(key, entry), output| output[key.to_s] = value(entry) }
+      else
+        input
+      end
+    end
+  end
+
+  module Sources
+    def amplitude = Source.new("amplitude")
+    def fft_spectrum = Source.new("fft_spectrum")
+    def beat? = Source.new("beat")
+    def beat = Source.new("beat")
+    def beat_pulse = Source.new("beat_pulse")
+    def beat_confidence = Source.new("beat_confidence")
+    def bass = Source.new("band", "low")
+    def low = Source.new("band", "low")
+    def mid = Source.new("band", "mid")
+    def treble = Source.new("band", "high")
+    def high = Source.new("band", "high")
+    def kick = Source.new("drum", "kick")
+    def snare = Source.new("drum", "snare")
+    def hihat = Source.new("drum", "hihat")
+
+    def frequency_band(name)
+      Source.new("band", name)
+    end
+
+    def onset(name = nil)
+      name ? Source.new("onset", name) : Source.new("onset")
+    end
+  end
+
+  class ShapeBuilder
+    include Sources
+
+    def initialize(type, attrs = {})
+      @shape = { "type" => type.to_s, "mappings" => [] }.merge(Normalizer.value(attrs))
+    end
+
+    def map(source = nil, target = nil, **options)
+      if source.is_a?(Hash)
+        source.each { |entry_source, entry_target| add_mapping(entry_source, entry_target, options) }
+      else
+        add_mapping(source, target || options.delete(:to), options)
+      end
+    end
+
+    def to_h = @shape
+
+    private
+
+    def add_mapping(source, target, options)
+      @shape["mappings"] << {
+        "source" => Normalizer.value(source),
+        "target" => target.to_s,
+        "transform" => Normalizer.value(options)
+      }
+    end
+
+    def method_missing(name, *args, &block)
+      return Source.new(name) if args.empty? && !block
+
+      @shape[name.to_s] = args.length <= 1 ? Normalizer.value(args.first) : Normalizer.value(args)
+    end
+
+    def respond_to_missing?(_name, _include_private = false) = true
+  end
+
+  class LayerBuilder
+    include Sources
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_s
+      @type = "geometry"
+      @shader = nil
+      @params = {}
+      @mappings = []
+      @param_schema = []
+    end
+
+    def type(value)
+      @type = value.to_s
+    end
+
+    def shader(value, **options)
+      @type = "shader"
+      @shader = value.to_s
+      @params.merge!(Normalizer.value(options))
+    end
+
+    def glsl(path, **options)
+      @type = "shader"
+      @shader = "custom"
+      @params["glsl"] = path.to_s
+      @params.merge!(Normalizer.value(options))
+    end
+
+    def palette(*colors)
+      @params["palette"] = colors.map(&:to_s)
+    end
+
+    def blend(value)
+      @params["blend"] = value.to_s
+    end
+
+    def effect(value, **options)
+      @params["effect"] = value.to_s
+      @params["effect_options"] = Normalizer.value(options) unless options.empty?
+    end
+
+    def param(name, default:, range: nil, step: nil)
+      schema = { "name" => name.to_s, "default" => default }
+      if range
+        schema["min"] = range.begin
+        schema["max"] = range.end
+      end
+      schema["step"] = step if step
+      @param_schema << schema
+      @params["param_" + name.to_s] = default
+    end
+
+    def circle(count: 1, **attrs, &block)
+      shape = ShapeBuilder.new(:circle, { count: count }.merge(attrs))
+      shape.instance_eval(&block) if block
+      (@params["shapes"] ||= []) << shape.to_h
+    end
+
+    def line(**attrs)
+      (@params["shapes"] ||= []) << { "type" => "line" }.merge(Normalizer.value(attrs))
+    end
+
+    def map(source = nil, target = nil, **options)
+      if source.is_a?(Hash)
+        source.each { |entry_source, entry_target| add_mapping(entry_source, entry_target, options) }
+      else
+        add_mapping(source, target || options.delete(:to), options)
+      end
+    end
+
+    def to_h
+      output = {
+        "name" => name,
+        "type" => @type,
+        "params" => @params,
+        "mappings" => @mappings
+      }
+      output["shader"] = @shader if @shader
+      output["param_schema"] = @param_schema unless @param_schema.empty?
+      output
+    end
+
+    private
+
+    def add_mapping(source, target, options)
+      @mappings << {
+        "source" => Normalizer.value(source),
+        "target" => target.to_s,
+        "transform" => Normalizer.value(options)
+      }
+    end
+
+    def method_missing(name, *args, &block)
+      return Source.new(name) if args.empty? && !block
+
+      @params[name.to_s] = args.length <= 1 ? Normalizer.value(args.first) : Normalizer.value(args)
+    end
+
+    def respond_to_missing?(_name, _include_private = false) = true
+  end
+
+  class SceneBuilder
+    def initialize(name)
+      @name = name.to_s
+      @layers = []
+    end
+
+    def layer(name, &block)
+      builder = LayerBuilder.new(name)
+      builder.instance_eval(&block) if block
+      @layers << builder.to_h
+    end
+
+    def to_h
+      { "name" => @name, "layers" => @layers }
+    end
+  end
+
+  class TransitionBuilder
+    def initialize(from, to)
+      @transition = { "from" => from.to_s, "to" => to.to_s }
+    end
+
+    def on_bar(value)
+      @transition["on_bar"] = value
+    end
+
+    def effect(value, **options)
+      @transition["effect"] = value.to_s
+      @transition["duration"] = options[:duration] if options.key?(:duration)
+    end
+
+    def to_h = @transition
+  end
+
+  class DefinitionBuilder
+    include Sources
+
+    def initialize
+      @scenes = []
+      @transitions = []
+      @globals = {}
+    end
+
+    def scene(name, **_options, &block)
+      builder = SceneBuilder.new(name)
+      builder.instance_eval(&block) if block
+      @scenes << builder.to_h
+    end
+
+    def transition(from:, to:, &block)
+      builder = TransitionBuilder.new(from, to)
+      builder.instance_eval(&block) if block
+      @transitions << builder.to_h
+    end
+
+    def set(name, value)
+      @globals[name.to_s] = Normalizer.value(value)
+    end
+
+    def to_h
+      { "scenes" => @scenes, "transitions" => @transitions, "globals" => @globals }
+    end
+
+    def method_missing(_name, *_args, &_block)
+      nil
+    end
+
+    def respond_to_missing?(_name, _include_private = false) = true
+  end
+
+  class << self
+    attr_accessor :current_definition
+
+    def compile_and_post(id, encoded)
+      source = Base64.decode64(encoded).force_encoding("UTF-8")
+      self.current_definition = nil
+      definition = TOPLEVEL_BINDING.eval(source, "playground.rb", 1)
+      definition = current_definition unless definition.is_a?(Hash)
+      definition ||= { "scenes" => [], "transitions" => [], "globals" => {} }
+      JS.global.postMessage({
+        type: "compiled",
+        id: id,
+        definition_json: JSON.generate(definition)
+      }.to_js)
+    rescue Exception => error
+      JS.global.postMessage({
+        type: "error",
+        id: id,
+        message: error.message,
+        backtrace: Array(error.backtrace).first(8)
+      }.to_js)
+    end
+  end
+end
+
+module Vizcore
+  def self.define(&block)
+    builder = VizcorePlayground::DefinitionBuilder.new
+    builder.instance_eval(&block) if block
+    VizcorePlayground.current_definition = builder.to_h
+  end
+end
+`;
+
+let vmPromise = null;
+
+const postStatus = (message) => {
+  self.postMessage({ type: "status", message });
+};
+
+const compileWasm = async (response) => {
+  try {
+    return await WebAssembly.compileStreaming(response);
+  } catch (_error) {
+    const fallbackResponse = await fetch(RUBY_WASM_URL);
+    return WebAssembly.compile(await fallbackResponse.arrayBuffer());
+  }
+};
+
+const initializeVm = async () => {
+  postStatus("Loading Ruby wasm");
+  const response = await fetch(RUBY_WASM_URL);
+  const rubyModule = await compileWasm(response);
+  const { vm } = await DefaultRubyVM(rubyModule);
+  vm.eval(DSL_RUNTIME);
+  self.postMessage({ type: "ready" });
+  return vm;
+};
+
+const getVm = () => {
+  vmPromise ||= initializeVm();
+  return vmPromise;
+};
+
+const encodeBase64 = (source) => {
+  const bytes = new TextEncoder().encode(source);
+  let binary = "";
+  const chunkSize = 0x8000;
+  for (let index = 0; index < bytes.length; index += chunkSize) {
+    const chunk = bytes.subarray(index, index + chunkSize);
+    binary += String.fromCharCode(...chunk);
+  }
+  return btoa(binary);
+};
+
+self.addEventListener("message", async (event) => {
+  const message = event.data || {};
+  if (message.type !== "compile") return;
+
+  try {
+    const vm = await getVm();
+    postStatus("Evaluating Ruby DSL");
+    vm.eval('VizcorePlayground.compile_and_post(' + Number(message.id) + ', "' + encodeBase64(String(message.source || "")) + '")');
+  } catch (error) {
+    self.postMessage({
+      type: "error",
+      id: message.id,
+      message: error instanceof Error ? error.message : String(error),
+      backtrace: []
+    });
+  }
+});