🌀 The Double Pendulum Engine

At its heart, Pendulos simulates a double pendulum – two masses connected by massless rods. The motion is chaotic: tiny changes in initial conditions lead to completely different trajectories. This chaos is what makes the instrument infinitely expressive.

• State variables: θ₁, θ₂ (angles), ω₁, ω₂ (angular velocities).
• Physics parameters: Masses, lengths, gravity, damping – all adjustable in real time.
• Integration: Uses RK4 (Runge‑Kutta 4th order) for accurate simulation.
• Visual feedback: The pendulum is drawn with a glowing trail; energy bar shows current intensity.
• Interaction: Click and drag either bob to instantly change the pendulum’s state.

The simulation runs at up to 120 steps per second. The Animation Speed controls how fast the simulation progresses – slower speeds let you hear subtle changes, faster speeds create frantic rhythms.

🎛️ Sound Engine: FM Synth & Euclidean Drums

Pendulos has two independent sound engines – you switch between them with the Mode Toggle. Both share the same master effects (reverb, delay).

🎵 FM Synth (3 Voices)

• Voice architecture: Each voice uses a carrier oscillator frequency‑modulated by a second oscillator. The carrier’s pitch follows a scale derived from the pendulum angles (see below).
• Per‑voice controls: Waveform (sine, triangle, sawtooth, square), Volume, Filter cutoff & Q, FM Depth & Ratio, Pan, and Detune (cents).
• Scale mapping: The pitch of each voice is calculated by mapping the pendulum angles (θ₁, θ₂) to scale degrees. The scale can be one of 17 presets or a Custom scale (comma‑separated semitone offsets).
• Mono‑to‑poly: The three voices are tuned to different ranges (bass, lead, pad) and respond to different aspects of the motion (e.g., Voice 1 follows θ₁, Voice 2 follows θ₂, Voice 3 follows a combination).
• MIDI out: When enabled, the fundamental frequencies of the voices are sent as MIDI notes to the selected output port.

🥁 Euclidean Drums (3 Tones)

• Rhythm generation: Each tone plays a Euclidean rhythm – a pattern of steps and pulses that distributes hits as evenly as possible. Rotation shifts the pattern in time.
• Per‑tone controls: Steps (2–32), Pulses (1–16), Rotation (0–31), Pitch, Pan, FM Depth/Ratio, Volume, Mute, and modulation amounts for pitch, volume, and FM.
• Two modulation modes:
  • Sound modulation: The pendulum’s energy and angles modulate pitch, volume, and FM depth of each tone – creating dynamic, evolving timbres.
  • Rhythm modulation: The pendulum modulates steps, pulses, and rotation in real time – making the rhythms themselves chaotic and unpredictable.
• Scale‑aware: Enable “Use Scale for Pitch” in the global drum controls to make drum pitches follow the same scale as the FM synth – turning rhythmic patterns into melodic sequences.
• Global drum parameters: BPM (linked to animation speed), Drum Volume, Decay, Reverb Send, Delay Send, and Energy Boost (amplifies the effect of pendulum energy on volume).

⚡ Speed Control & Energy Follow

The Animation Speed determines how fast the pendulum moves and directly maps to the drum BPM (30–240). You can choose from five speed sources:

• Manual – The slider sets a fixed speed. Enable Energy Follow to automatically scale both speed and master volume based on the pendulum’s energy. Sensitivity controls how much the energy affects the scaling.
• Envelope Follower – Speed follows the pendulum’s energy envelope. Use Invert to make speed decrease with energy, and Smoothing to control the responsiveness.
• Light Sensor – Speed follows ambient light (via the device’s light sensor). Invert, Threshold (minimum light level to trigger) are adjustable.
• Lorenz Attractor – Speed is driven by the chaotic Lorenz system. Set Min and Max speed bounds to constrain the range.
• Camera (Motion) – Speed follows the amount of motion detected by your webcam. Wave your hand, dance, or move objects to control speed. Adjust Sensitivity (0.1–50), Invert, and Smoothing to tune the response. Higher sensitivity makes even small motions drive the speed to maximum.

Energy Follow (Manual mode only): When enabled, the effective speed becomes base_speed × (1 − sensitivity + sensitivity × normalized_energy). The master volume is also scaled by the same factor – so the pendulum naturally slows down and fades as it loses energy, creating an organic, breathing performance.

🔀 Modulation Routing Matrix

The Modulation Matrix lets you map any source to any target parameter, with Amount and Invert per row. The matrix starts empty – you build your own custom routings.

• Sources: Envelope (pendulum energy), Light Sensor, LFO (sine wave, 0.2 Hz), OSC In (manual slider), Theta1, Theta2, Omega1, Omega2.
• Targets (FM Synth): Speed, Damping, Gravity, Master Volume, Reverb, Delay Time, and for each voice: FM Depth, FM Ratio, Detune, Filter, Pan.
• Targets (Drums): Pitch, Pitch Mod, FM Mod, FM Depth for each tone, and Drum Decay (global).
• Usage: Click “＋ Add Row” to create a row, select source and target from the dropdowns, adjust the Amount slider (0–1), and optionally tick Invert. Rows can be removed individually or cleared with “🗑 Clear All”.
• Real‑time: Modulation is applied every frame – the effect is immediate and continuous.

Example: Route Envelope → Voice 1 Filter with Amount 0.5. As the pendulum swings, the filter cutoff sweeps up and down, adding dynamic expression.

📡 OSC (Open Sound Control)

Pendulos sends real‑time data via OSC to a configurable UDP port. This allows you to connect to Max/MSP, Pure Data, TouchDesigner, or any OSC‑compatible software.

• Outgoing messages: /pendulum/theta1, /theta2, /omega1, /omega2, /energy, /speed.
• Configuration: Set the Host (IP) and Port in the OSC panel, then click “🔌 Enable” to start sending.
• Manual OSC In: A slider labelled “Manual OSC In” lets you simulate incoming OSC data – it injects a value (0–1) into the modulation system as the OSC In source. Use it to test modulation routing without external hardware.
• Incoming parameter mapping: You can also receive OSC messages to control parameters directly: /param/speed, /param/damping, /param/gravity, /param/masterVol, /param/reverb, /param/delay. This is useful for external controllers.

📱 Sensors & Environmental Control

Pendulos can respond to your device’s physical environment in two ways:

• Device Sensors: Gyroscope (alpha, beta, gamma) and Ambient Light sensor. Once enabled, they modulate physics parameters (lengths, masses, gravity, damping, speed) in real time. You can choose which parameter each sensor maps to via dropdowns.
• Weather & Motion: The Environmental Modulation panel fetches live weather data (temperature, wind speed, atmospheric pressure) using the Open‑Meteo API and also uses device motion (acceleration) to influence the pendulum. The Env Blend slider controls how much of this environmental data is applied.
• Usage: Click “🌍 Show Environmental CTRL” to open the panel. Press “📍 Load Weather” to fetch weather data (geolocation required). Press “📱 Enable Sensors” to request motion sensor permissions. Toggle “Enable Environmental Control” to activate the modulations.

🎙️ Recording & Replay

Capture entire performances – both audio and parameter data – and replay them later with full fidelity.

• Recording: Click ⏺ Start Recording to start capturing:
  • Audio: WebM/Opus (stereo) from the master output.
  • Parameter log: Every 100 ms, the current state (angles, velocities, speed, damping, gravity, master volume, reverb, delay) is recorded.
• Export: After stopping, you can:
  • ⬇ Export WebM: Download the audio as a WebM file.
  • ⬇ Export WAV: Convert the audio to lossless WAV (DAW‑ready).
  • 💾 Save Score: Save the parameter log as a JSON file (the “score”).
• Replay: Click 📂 Load Score to select a previously saved JSON score. The performance will replay with linear interpolation between recorded frames, driving both the pendulum visual and the sound engine. You can stop replay at any time with ⏹ Stop Replay.
• Use case: Perfect for capturing happy accidents, building a library of performances, or using as a generative composition tool.

🎮 Controls & UI

• Drag the masses: Click and drag either pendulum bob to instantly set new initial conditions – great for hands‑on improvisation.
• Physics sliders: Mass 1/2, Length 1/2, Gravity, Damping – all adjustable in real time.
• Animation Speed: The main speed slider (in Manual mode) controls both the simulation step rate and drum BPM.
• Play / Pause: Pauses the simulation (sound stops) – pendulum freezes.
• Reset Pendulum: Randomizes angles and velocities – starts a new chaotic trajectory.
• Auto‑restart: When energy drops below the threshold (0–10), the pendulum resets randomly – keeps the chaos going forever.
• Reset Defaults: Two separate buttons reset all Synth parameters or all Drum parameters to their factory defaults.
• Scale: Cycle through 17 preset scales. When “Custom” appears, enter comma‑separated semitone offsets (e.g. 0,2,4,7,9) and click Apply. The scale affects both FM synth pitches and (optionally) drum pitches.
• Mode Toggle: Switch between FM Synth and Euclidean Drums – the UI adapts to show the relevant controls.
• Mute: Global mute for all audio.
• Fullscreen: Hides all controls – fill the screen with the pendulum visualization.
• Theme: Toggle between dark and light modes.
• Panel Toggles: Header buttons 📡 OSC, 🔀 Mod, 🎙️ Rec and 🌍 Show Environmental CTRL show/hide their respective panels. Panels start closed for a clean UI.

💡 Tips & Workflow

• Start simple: Use Manual speed mode with a moderate speed (1.0) and the Pentatonic scale. Drag the pendulum to get a feel for the relationship between motion and sound.
• Add expression: Enable Energy Follow to make the performance breathe naturally – the tempo and volume respond to the pendulum's energy.
• Build modulations: Use the Modulation Matrix to route Envelope (energy) to Voice 1 Filter, or Light Sensor to Reverb, etc. Start with one or two rows and experiment.
• Explore drum rhythms: In Drum mode, adjust Steps, Pulses, and Rotation for each tone. Switch between Sound and Rhythm modulation modes to control different aspects of the drums with the pendulum.
• Use scales with drums: Enable “Use Scale for Pitch” and select a scale – drum pitches will follow the scale, creating melodic rhythmic patterns.
• Camera speed: If the camera response feels too slow, increase the Sensitivity slider (up to 50) and reduce Smoothing for snappier reaction. Even small hand movements will drive the speed to maximum.
• Record and replay: Capture a performance, export the score, then reload it later to replay the exact same gestures – perfect for live sets or sound design.
• Use with external gear: Send OSC to Max/MSP, Pure Data, or any OSC‑compatible software. Use the incoming OSC slider to test modulation from external sources.
• MIDI: Connect a MIDI output to your DAW or hardware synth to control external instruments from the pendulum.
• Environmental modulation: Combine weather data with device motion to create unpredictable, site‑specific performances – the piece changes with the weather and your movement.

🔧 Under the Hood

• Audio: Built with the Web Audio API – uses oscillators, gain nodes, biquad filters, stereo panners, convolution reverb (custom impulse response), and delay with feedback.
• Physics: RK4 integration for high accuracy. The system is deterministic – same initial conditions produce the same trajectory.
• Performance: Optimised for 60 fps – the audio callback runs at the native sample rate, while the physics and modulation update every animation frame.
• Security: Camera, geolocation, and sensor access require user permission and are only active when the corresponding features are enabled.
• Compatibility: Works on modern desktop and mobile browsers (Chrome, Firefox, Safari, Edge) with Web Audio, getUserMedia, and WebRTC support.