vizcore 0.1.0 → 1.0.0

data/sig/vizcore.rbs

@@ -0,0 +1,362 @@
+module Vizcore
+  VERSION: String
+
+  def self.root: () -> Pathname
+  def self.frontend_root: () -> Pathname
+  def self.templates_root: () -> Pathname
+  def self.define: () { () -> void } -> Hash[Symbol, untyped]
+  def self.plugin: (String | Symbol name) -> bool
+  def self.register_layer_capability: (
+    type: Symbol | String,
+    ?aliases: Array[Symbol | String] aliases,
+    ?params: Hash[Symbol | String, String] params,
+    ?mappable_params: Array[Symbol | String] mappable_params,
+    ?description: String? description
+  ) -> Vizcore::LayerCatalog::Capability
+end
+
+module Vizcore::LayerCatalog
+  class Capability < Struct[untyped]
+    attr_accessor type: Symbol
+    attr_accessor aliases: Array[Symbol]
+    attr_accessor params: Hash[Symbol, String]
+    attr_accessor mappable_params: Array[Symbol]
+    attr_accessor description: String
+
+    def types: () -> Array[Symbol]
+    def supports?: (untyped value) -> bool
+  end
+
+  def self.capabilities: () -> Array[Capability]
+  def self.capability_for: (untyped type) -> Capability?
+  def self.supported_type?: (untyped type) -> bool
+  def self.supported_types: () -> Array[Symbol]
+  def self.params_for: (untyped type) -> Hash[Symbol, String]
+  def self.mappable_params_for: (untyped type) -> Array[Symbol]
+  def self.register_layer_capability: (
+    type: Symbol | String,
+    ?aliases: Array[Symbol | String] aliases,
+    ?params: Hash[Symbol | String, String] params,
+    ?mappable_params: Array[Symbol | String] mappable_params,
+    ?description: String? description
+  ) -> Capability
+  def self.reset_plugin_capabilities!: () -> Array[Capability]
+  def self.plugin_capabilities: () -> Array[Capability]
+end
+
+module Vizcore
+  class ControlPreset
+    def self.load: (String | Pathname path) -> Hash[String, untyped]
+    def self.write: (String | Pathname path, Hash[untyped, untyped] payload) -> Hash[String, untyped]
+    def initialize: (String | Pathname path) -> void
+    def load: () -> Hash[String, untyped]
+    def write: (Hash[untyped, untyped] payload) -> Hash[String, untyped]
+  end
+
+  class ProjectManifest
+    attr_reader path: Pathname
+    attr_reader root: Pathname
+
+    def self.load: (String | Pathname path) -> ProjectManifest
+    def initialize: (String | Pathname path) -> void
+    def config_defaults: (?profile: String? profile) -> Hash[Symbol, untyped]
+    def plugins: (?profile: String? profile) -> Array[String]
+    def plugin_assets: (?profile: String? profile) -> Array[Pathname]
+    def profile_names: () -> Array[String]
+  end
+end
+
+module Vizcore::CLISupport
+  class DslReference
+    def lines: () -> Array[String]
+  end
+end
+
+module Vizcore::Sync
+  class OscMessage
+    attr_reader address: String
+    attr_reader arguments: Array[untyped]
+
+    def self.parse: (String data) -> OscMessage?
+    def initialize: (address: String, ?arguments: Array[untyped] arguments) -> void
+  end
+
+  class OscReceiver
+    DEFAULT_HOST: String
+    MAX_PACKET_SIZE: Integer
+
+    def initialize: (
+      port: Integer port,
+      ?host: String host,
+      handler: untyped handler,
+      ?error_reporter: untyped? error_reporter
+    ) -> void
+    def start: () -> OscReceiver
+    def stop: () -> nil
+  end
+end
+
+module Vizcore::Analysis
+  class FeatureRecorder
+    VERSION: String
+    DEFAULT_FRAME_COUNT: Integer
+    DEFAULT_FRAME_RATE: Float
+
+    def initialize: (
+      audio_file: String | Pathname audio_file,
+      ?frames: Integer frames,
+      ?fps: Numeric fps,
+      ?noise_gate: Numeric noise_gate,
+      ?audio_normalize: Hash[Symbol, untyped]? audio_normalize,
+      ?bpm: Numeric? bpm,
+      ?bpm_lock: bool bpm_lock
+    ) -> void
+
+    def write: (out: String | Pathname) -> Hash[Symbol, untyped]
+  end
+
+  class FeatureReplay
+    attr_reader metadata: Hash[Symbol, untyped]
+
+    def initialize: (path: String | Pathname path) -> void
+    def call: (?Array[Float]? samples) -> Hash[Symbol, untyped]
+    def frame_count: () -> Integer
+  end
+end
+
+module Vizcore::DSL
+  type source = { kind: Symbol, ?band: Symbol }
+  type transform = {
+    ?gain: Float,
+    ?min: Float,
+    ?max: Float,
+    ?curve: Symbol,
+    ?deadzone: Float,
+    ?attack: Float,
+    ?release: Float
+  }
+  type mapping = { source: source, target: Symbol, ?transform: transform }
+  type param_schema_entry = {
+    name: Symbol,
+    ?default: Float,
+    ?min: Float,
+    ?max: Float,
+    ?step: Float
+  }
+  type layer = {
+    name: Symbol,
+    type: Symbol,
+    params: Hash[Symbol, untyped],
+    ?shader: Symbol,
+    ?glsl: String,
+    ?param_schema: Array[param_schema_entry],
+    ?mappings: Array[mapping]
+  }
+  type scene = { name: Symbol, layers: Array[layer], ?theme: Symbol }
+  type style = { name: Symbol, params: Hash[Symbol, untyped] }
+  type theme = { name: Symbol, params: Hash[Symbol, untyped] }
+  type timeline_entry = { at: Float, unit: Symbol, scene: Symbol }
+  type key_action = { type: Symbol, ?scene: String, ?control: Symbol }
+  type key_mapping = { key: String, action: key_action }
+
+  class Engine
+    def self.define: () { () -> void } -> Hash[Symbol, untyped]
+    def self.load_file: (String | Pathname path) -> Hash[Symbol, untyped]
+    def self.watch_file: (String | Pathname path, ?poll_interval: Float poll_interval, ?listener_factory: untyped listener_factory) { (Hash[Symbol, untyped], Pathname) -> void } -> FileWatcher
+
+    def audio: (Symbol | String name, **untyped options) -> Array[Hash[Symbol, untyped]]
+    def style: (Symbol | String name) { () -> void } -> void
+    def theme: (Symbol | String name) { () -> void } -> void
+    def midi: (Symbol | String name, **untyped options) -> Array[Hash[Symbol, untyped]]
+    def audio_normalize: (?mode: Symbol | String mode, **untyped options) -> Hash[Symbol, untyped]
+    def bpm: (Numeric value) -> Float
+    def bpm_lock: () -> bool
+                | (bool value) -> bool
+    def tap_tempo: (?key: Symbol | String key) -> Hash[Symbol, untyped]
+    def key: (Symbol | String value) { () -> void } -> void
+    def scene: (Symbol | String name, ?extends: Symbol | String? extends) { () -> void } -> void
+    def section: (Symbol | String name, bars: Integer bars, ?beats_per_bar: Integer beats_per_bar) { () -> void } -> void
+    def timeline: (?beats_per_bar: Integer beats_per_bar) { () -> void } -> void
+    def transition: (from: Symbol | String, to: Symbol | String) { () -> void } -> void
+    def midi_map: (?note: Integer? note, ?cc: Integer? cc, ?pc: Integer? pc) { (*untyped) -> void } -> void
+    def set: (Symbol | String key, untyped value) -> untyped
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class TimelineBuilder
+    DEFAULT_BEATS_PER_BAR: Integer
+
+    class Point < Struct[untyped]
+      attr_accessor value: Float
+      attr_accessor unit: Symbol
+    end
+
+    def initialize: (?beats_per_bar: Integer beats_per_bar) -> void
+    def evaluate: () ?{ () -> void } -> TimelineBuilder
+    def at: (Numeric | Point position, scene: Symbol | String scene) -> timeline_entry
+    def seconds: (Numeric value) -> Point
+    def beats: (Numeric value) -> Point
+    def bars: (Numeric value, ?beats_per_bar: Integer? beats_per_bar) -> Point
+    def to_h: () -> Array[timeline_entry]
+    def transitions: () -> Array[Hash[Symbol, untyped]]
+  end
+
+  class Engine::TransitionBuilder
+    def initialize: () -> void
+    def effect: (Symbol | String name, **untyped options) -> void
+    def trigger: () { () -> bool } -> void
+    def on_beat: (Integer count) -> void
+    def on_bar: (Integer count, ?beats_per_bar: Integer beats_per_bar) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Engine::KeyBindingBuilder
+    def initialize: () -> void
+    def switch_scene: (Symbol | String name) -> void
+    def blackout: () -> void
+    def freeze: () -> void
+    def live_control: (Symbol | String control) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class SceneBuilder
+    def initialize: (
+      name: Symbol | String name,
+      ?styles: Hash[Symbol, Hash[Symbol, untyped]] styles,
+      ?themes: Hash[Symbol, Hash[Symbol, untyped]] themes,
+      ?layers: Array[layer] layers
+    ) -> void
+    def evaluate: () ?{ () -> void } -> SceneBuilder
+    def layer: (Symbol | String name) ?{ () -> void } -> void
+    def group: (Symbol | String name) { () -> void } -> void
+    def use_theme: (Symbol | String name) -> Hash[Symbol, untyped]
+    def to_h: () -> scene
+  end
+
+  class LayerGroupBuilder
+    def initialize: (
+      name: Symbol | String name,
+      ?styles: Hash[Symbol, Hash[Symbol, untyped]] styles,
+      ?defaults: Hash[Symbol, untyped] defaults
+    ) -> void
+    def evaluate: () ?{ () -> void } -> LayerGroupBuilder
+    def layer: (Symbol | String name) ?{ () -> void } -> void
+    def blend: (Symbol | String value) -> Symbol
+    def opacity: (Numeric value) -> Float
+    def effect: (Symbol | String value) -> Symbol
+    def effect_intensity: (Numeric value) -> Float
+    def vj_effect: (Symbol | String value) -> Symbol
+    def geometry: (Symbol | String value) -> Symbol
+    def material: (Symbol | String value) -> Symbol
+    def scale: (Numeric value) -> Float
+    def deform: (Numeric value) -> Float
+    def color_shift: (Numeric value) -> Float
+    def palette: (*untyped colors) -> Array[String]
+    def use_style: (Symbol | String name) -> Hash[Symbol, untyped]
+    def to_a: () -> Array[layer]
+  end
+
+  class StyleBuilder
+    def initialize: (name: Symbol | String name, ?kind: String kind) -> void
+    def evaluate: () ?{ () -> void } -> StyleBuilder
+    def palette: (*untyped colors) -> Array[String]
+    def to_h: () -> style
+  end
+
+  class LayerBuilder
+    def initialize: (
+      name: Symbol | String name,
+      ?styles: Hash[Symbol, Hash[Symbol, untyped]] styles,
+      ?defaults: Hash[Symbol, untyped] defaults
+    ) -> void
+    def evaluate: () ?{ () -> void } -> LayerBuilder
+    def type: (Symbol | String value) -> Symbol
+    def shader: (Symbol | String value, ?reload: bool? reload) -> Symbol
+    def glsl: (String | Pathname path) -> String
+    def file: (String | Pathname path) -> String
+    def circle: (**untyped options) ?{ () -> void } -> Hash[Symbol, untyped]
+    def line: (**untyped options) ?{ () -> void } -> Hash[Symbol, untyped]
+    def draw: () { () -> void } -> Array[Hash[Symbol, untyped]]
+    def source: (Symbol | String value, **untyped options) -> (Symbol | source)
+    def count: (Integer value) -> Integer
+    def content: (String value) -> String
+    def font_size: (Integer value) -> Integer
+    def letter_spacing: (Numeric value) -> Float
+    def align: (Symbol | String value) -> Symbol
+    def font: (String value) -> String
+    def fill: (String value) -> String
+    def stroke: (?untyped value, ?width: Numeric? width, ?color: String? color) -> Hash[Symbol, untyped]
+    def shadow: (?color: String? color, ?blur: Numeric? blur) -> Hash[Symbol, untyped]
+    def blend: (Symbol | String value) -> Symbol
+    def opacity: (Numeric value) -> Float
+    def effect: (Symbol | String value) -> Symbol
+    def effect_intensity: (Numeric value) -> Float
+    def vj_effect: (Symbol | String value) -> Symbol
+    def geometry: (Symbol | String value) -> Symbol
+    def material: (Symbol | String value) -> Symbol
+    def scale: (Numeric value) -> Float
+    def deform: (Numeric value) -> Float
+    def color_shift: (Numeric value) -> Float
+    def palette: (*untyped colors) -> Array[String]
+    def use_style: (Symbol | String name) -> Hash[Symbol, untyped]
+    def param: (
+      Symbol | String name,
+      ?default: Numeric? default,
+      ?range: Range[Numeric]? | [Numeric, Numeric]? range,
+      ?min: Numeric? min,
+      ?max: Numeric? max,
+      ?step: Numeric? step
+    ) -> Hash[Symbol, untyped]
+    def map: (?Hash[untyped, untyped] | Symbol | String definition, **untyped options) ?{ () -> void } -> void
+    def react_to: (Hash[Symbol, untyped] | Symbol | String source_value) { () -> void } -> void
+    def amplitude: () -> source
+    def frequency_band: (Symbol | String name) -> source
+    def sub: () -> source
+    def low: () -> source
+    def bass: () -> source
+    def mid: () -> source
+    def high: () -> source
+    def treble: () -> source
+    def fft_spectrum: () -> source
+    def onset: () -> source
+             | (Symbol | String band) -> source
+    def kick: () -> source
+            | (untyped value) -> untyped
+    def snare: () -> source
+             | (untyped value) -> untyped
+    def hihat: () -> source
+             | (untyped value) -> untyped
+    def beat?: () -> source
+    def beat: () -> source
+    def beat_confidence: () -> source
+    def beat_pulse: () -> source
+    def beat_count: () -> source
+    def bpm: () -> source
+    def to_h: () -> layer
+  end
+
+  class ReactionBuilder
+    def initialize: (mapping_factory: ^(Symbol | String, Hash[Symbol, untyped]) -> mapping mapping_factory) -> void
+    def evaluate: () { () -> void } -> Array[mapping]
+    def change: (Symbol | String target, **untyped options) -> mapping
+    def trigger: (Symbol | String target, **untyped options) -> mapping
+  end
+
+  class MappingTransformBuilder
+    def initialize: (?Hash[untyped, untyped] initial) -> void
+    def evaluate: () ?{ () -> void } -> MappingTransformBuilder
+    def gain: (Numeric value) -> Numeric
+    def range: (Range[Numeric] | [Numeric, Numeric] value) -> (Range[Numeric] | [Numeric, Numeric])
+    def min: (Numeric value) -> Numeric
+    def max: (Numeric value) -> Numeric
+    def curve: (Symbol | String value) -> (Symbol | String)
+    def deadzone: (Numeric value) -> Numeric
+    def smooth: (?attack: Numeric? attack, ?release: Numeric? release) -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class MappingResolver
+    def initialize: () -> void
+    def resolve_layers: (scene_layers: Array[Hash[Symbol, untyped]], audio: Hash[Symbol, untyped]) -> Array[Hash[Symbol, untyped]]
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vizcore
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -90,73 +90,153 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
-- docs/GETTING_STARTED.md
+- docs/.nojekyll
+- docs/assets/site.css
+- docs/assets/vizcore-demo.gif
+- docs/assets/vizcore-poster.png
+- docs/assets/vj-tunnel.js
+- docs/index.html
+- examples/README.md
+- examples/assets/README.md
 - examples/assets/complex_demo_loop.wav
+- examples/audio_inspector.rb
 - examples/basic.rb
+- examples/club_intro_drop.rb
 - examples/complex_audio_showcase.rb
 - examples/custom_shader.rb
 - examples/file_audio_demo.rb
 - examples/intro_drop.rb
+- examples/kansai_rubykaigi_visual.rb
+- examples/live_coding_minimal.rb
+- examples/midi_controller_show.rb
 - examples/midi_scene_switch.rb
+- examples/parser_visualizer.rb
+- examples/readme_demo.rb
+- examples/rhythm_geometry.rb
+- examples/ruby_crystal_show.rb
+- examples/shader_playground.rb
 - examples/shaders/custom_wave.frag
+- examples/unyo_liquid.rb
+- examples/vj_ambient_chill_room.rb
+- examples/vj_dnb_jungle.rb
+- examples/vj_festival_mainstage.rb
+- examples/vj_festival_mainstage.yml
+- examples/vj_glitch_industrial.rb
+- examples/vj_hiphop_cipher.rb
+- examples/vj_jpop_idol_live.rb
+- examples/vj_synthwave_retro.rb
+- examples/vj_techno_warehouse.rb
 - exe/vizcore
 - frontend/index.html
+- frontend/src/audio-inspector.js
+- frontend/src/live-controls.js
 - frontend/src/main.js
+- frontend/src/midi-learn.js
+- frontend/src/performance-monitor.js
+- frontend/src/plugin-runtime.js
+- frontend/src/projector-mode.js
 - frontend/src/renderer/engine.js
 - frontend/src/renderer/layer-manager.js
 - frontend/src/renderer/shader-manager.js
+- frontend/src/runtime-control-preset.js
+- frontend/src/shader-error-overlay.js
+- frontend/src/shader-param-controls.js
 - frontend/src/shaders/builtins.js
 - frontend/src/shaders/post-effects.js
+- frontend/src/visual-regression.js
+- frontend/src/visual-settings-preset.js
 - frontend/src/visuals/geometry.js
+- frontend/src/visuals/image-renderer.js
 - frontend/src/visuals/particle-system.js
+- frontend/src/visuals/spectrogram-renderer.js
 - frontend/src/visuals/text-renderer.js
 - frontend/src/visuals/vj-effects.js
 - frontend/src/websocket-client.js
 - lib/vizcore.rb
 - lib/vizcore/analysis.rb
+- lib/vizcore/analysis/adaptive_normalizer.rb
 - lib/vizcore/analysis/band_splitter.rb
 - lib/vizcore/analysis/beat_detector.rb
 - lib/vizcore/analysis/bpm_estimator.rb
+- lib/vizcore/analysis/feature_recorder.rb
+- lib/vizcore/analysis/feature_replay.rb
 - lib/vizcore/analysis/fft_processor.rb
 - lib/vizcore/analysis/fftw_ffi.rb
 - lib/vizcore/analysis/pipeline.rb
 - lib/vizcore/analysis/smoother.rb
+- lib/vizcore/analysis/tap_tempo.rb
 - lib/vizcore/audio.rb
 - lib/vizcore/audio/base_input.rb
 - lib/vizcore/audio/dummy_sine_input.rb
 - lib/vizcore/audio/file_input.rb
+- lib/vizcore/audio/fixture_input.rb
 - lib/vizcore/audio/input_manager.rb
 - lib/vizcore/audio/mic_input.rb
 - lib/vizcore/audio/midi_input.rb
 - lib/vizcore/audio/portaudio_ffi.rb
 - lib/vizcore/audio/ring_buffer.rb
 - lib/vizcore/cli.rb
+- lib/vizcore/cli/doctor.rb
+- lib/vizcore/cli/dsl_reference.rb
+- lib/vizcore/cli/layer_docs.rb
+- lib/vizcore/cli/scene_diagnostics.rb
+- lib/vizcore/cli/scene_inspector.rb
+- lib/vizcore/cli/scene_validator.rb
+- lib/vizcore/cli/shader_template.rb
+- lib/vizcore/cli/shader_uniform_docs.rb
 - lib/vizcore/config.rb
+- lib/vizcore/control_preset.rb
 - lib/vizcore/dsl.rb
 - lib/vizcore/dsl/engine.rb
 - lib/vizcore/dsl/file_watcher.rb
 - lib/vizcore/dsl/layer_builder.rb
+- lib/vizcore/dsl/layer_group_builder.rb
 - lib/vizcore/dsl/mapping_resolver.rb
+- lib/vizcore/dsl/mapping_transform_builder.rb
 - lib/vizcore/dsl/midi_map_executor.rb
+- lib/vizcore/dsl/reaction_builder.rb
 - lib/vizcore/dsl/scene_builder.rb
 - lib/vizcore/dsl/shader_source_resolver.rb
+- lib/vizcore/dsl/style_builder.rb
+- lib/vizcore/dsl/timeline_builder.rb
 - lib/vizcore/dsl/transition_controller.rb
 - lib/vizcore/errors.rb
+- lib/vizcore/layer_catalog.rb
+- lib/vizcore/project_manifest.rb
 - lib/vizcore/renderer.rb
 - lib/vizcore/renderer/frame_scheduler.rb
+- lib/vizcore/renderer/png_writer.rb
+- lib/vizcore/renderer/render_sequence.rb
+- lib/vizcore/renderer/scene_frame_source.rb
 - lib/vizcore/renderer/scene_serializer.rb
+- lib/vizcore/renderer/snapshot.rb
+- lib/vizcore/renderer/snapshot_renderer.rb
 - lib/vizcore/server.rb
 - lib/vizcore/server/frame_broadcaster.rb
+- lib/vizcore/server/gallery_app.rb
+- lib/vizcore/server/gallery_page.rb
+- lib/vizcore/server/gallery_runner.rb
 - lib/vizcore/server/rack_app.rb
 - lib/vizcore/server/runner.rb
+- lib/vizcore/server/scene_dependency_watcher.rb
 - lib/vizcore/server/websocket_handler.rb
+- lib/vizcore/sync.rb
+- lib/vizcore/sync/osc_message.rb
+- lib/vizcore/sync/osc_receiver.rb
 - lib/vizcore/templates/basic_scene.rb
 - lib/vizcore/templates/custom_shader_scene.rb
 - lib/vizcore/templates/custom_wave.frag
 - lib/vizcore/templates/intro_drop_scene.rb
 - lib/vizcore/templates/midi_control_scene.rb
+- lib/vizcore/templates/plugin_layer.rb
+- lib/vizcore/templates/plugin_readme.md
+- lib/vizcore/templates/plugin_renderer.js
+- lib/vizcore/templates/plugin_scene.rb
 - lib/vizcore/templates/project_readme.md
+- lib/vizcore/templates/rubykaigi_scene.rb
 - lib/vizcore/version.rb
+- scripts/browser_capture.mjs
+- sig/vizcore.rbs
 homepage: https://github.com/ydah/vizcore
 licenses:
 - MIT
@@ -164,7 +244,7 @@ metadata:
   homepage_uri: https://github.com/ydah/vizcore
   source_code_uri: https://github.com/ydah/vizcore
   changelog_uri: https://github.com/ydah/vizcore/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/ydah/vizcore/blob/main/docs/GETTING_STARTED.md
+  documentation_uri: https://ydah.github.io/vizcore/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/docs/GETTING_STARTED.md

@@ -1,105 +0,0 @@
-# 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.