# How to Integrate Folia with OBS Browser Source for Streaming

> Integrate Folia with OBS Browser Source for seamless streaming. Offload rendering and stream animations to OBS via EventSource for a smooth visualizer experience.

- Repository: [冬霧/folia-major](https://github.com/chthollyphile/folia-major)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Folia provides a dedicated OBS Browser Source integration that streams the visualizer animation to OBS while keeping heavy rendering off the main window via a local EventSource server.**

The `chthollyphile/folia-major` repository includes a built-in solution for live streaming your music visualizations. Instead of capturing the Folia application window directly—which consumes significant CPU and GPU resources—you can offload the visualizer rendering to an OBS Browser Source. This architecture separates the data processing from the visualization rendering, allowing Folia to publish audio analysis and playback state while OBS handles the graphics.

## How the Folia OBS Integration Works

The integration operates through three distinct layers that communicate via IPC and server-sent events.

### The Publisher Layer (Electron to OBS)

In the main Folia window, the `useObsBrowserSourcePublisher` hook gathers real-time playback data. Located in [`src/hooks/useObsBrowserSourcePublisher.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/hooks/useObsBrowserSourcePublisher.ts), this hook constructs clock signals, audio spectrum analysis, and configuration objects, then transmits them to the Electron main process through dedicated IPC channels.

When the OBS Browser Source is active, Folia sets an internal `isObsBrowserSourceRendering` flag to `true`. This signals the main UI to stop drawing the visualizer locally, freeing up resources for the stream.

### The Server Layer (EventSource Endpoint)

The Electron main process exposes three critical IPC methods: `publishObsBrowserSourceClock`, `publishObsBrowserSourceAudio`, and `publishObsBrowserSourceConfig`. These methods feed a local HTTP server that exposes an **EventSource** endpoint at `/obs/events?token=…`.

Clients (OBS) connect to this endpoint to receive a continuous stream of `config`, `clock`, and `audio` events. The server maintains the connection state and broadcasts updates whenever the playback state changes or new audio analysis data becomes available.

### The Renderer Layer (OBS Browser Source)

The actual visualization runs inside OBS through a minimal React application defined in [`src/components/obs/ObsBrowserSourceApp.tsx`](https://github.com/chthollyphile/folia-major/blob/main/src/components/obs/ObsBrowserSourceApp.tsx). This renderer connects to the EventSource URL, parses incoming events, and drives the visualizer using the same rendering engine as the main Folia UI.

The component automatically forces the device-pixel-ratio to ensure the visualizer renders at full resolution regardless of the OBS source window size. This prevents scaling artifacts when streaming at 1920×1080 or higher resolutions.

## Step-by-Step Integration Guide

Follow these steps to connect Folia to OBS Studio.

### Enable the OBS Browser Source in Folia

Open Folia’s settings and navigate to the integration options. The `IntegrationSettingsSubview` component in [`src/components/modal/settings/IntegrationSettingsSubview.tsx`](https://github.com/chthollyphile/folia-major/blob/main/src/components/modal/settings/IntegrationSettingsSubview.tsx) provides the toggle interface.

```typescript
// Inside IntegrationSettingsSubview.tsx
const handleToggle = () => void onToggleObsBrowserSource?.(!obsBrowserSourceStatus.enabled);

<div
  onClick={handleToggle}
  className="w-12 h-6 rounded-full p-1 …"
>
  {/* toggle UI */}
</div>

```

Once enabled, Folia displays the connection URL (e.g., `http://127.0.0.1:xxxx/obs/events?token=…`). Copy this address using the provided button.

### Configure OBS Studio

1. In OBS Studio, add a new **Browser** source to your scene.
2. Paste the copied URL into the URL field.
3. Set the width and height to match your stream resolution (default is **1920×1080**).
4. Keep "Shutdown source when not visible" checked to allow Folia to detect when OBS disconnects.

### Verify the Connection

When OBS connects successfully, Folia displays a **"Clients: 1"** badge in the UI. The main window visualizer will pause, confirming that rendering has shifted to the browser source. Start playback in Folia to see the visualization appear in OBS.

## Technical Implementation Details

Understanding the data flow helps troubleshoot connection issues and customize the integration.

### Data Types and IPC Methods

The exchanged data is strictly typed in [`src/types/obsBrowserSource.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/types/obsBrowserSource.ts). The three main event types are:

- **Config**: Theme settings and visualizer parameters
- **Clock**: Playback position, duration, and player state
- **Audio**: Spectrum data, audio power levels, and frequency band analysis (bass, midrange, treble)

The publisher hook uses `useCallback` to optimize transmission frequency:

```typescript
// useObsBrowserSourcePublisher.ts
const publishClock = useCallback(() => {
  if (!window.electron?.publishObsBrowserSourceClock) return;
  const nextClock = buildClock();
  lastPublishedClockRef.current = nextClock;
  lastClockPublishMsRef.current = nextClock.sentAtMs;
  void window.electron.publishObsBrowserSourceClock(nextClock).catch(console.warn);
}, [buildClock]);

```

### Optimizing Performance

The [`src/utils/obsBrowserSource.ts`](https://github.com/chthollyphile/folia-major/blob/main/src/utils/obsBrowserSource.ts) file contains helper functions for **clock resolution** and **spectrum down-sampling**. These utilities ensure that high-frequency audio data (typically 60fps) doesn't overwhelm the EventSource connection while maintaining smooth visualizations in OBS.

## Code Examples

### Connecting the EventSource in OBS

The [`ObsBrowserSourceApp.tsx`](https://github.com/chthollyphile/folia-major/blob/main/ObsBrowserSourceApp.tsx) component establishes the connection using standard EventSource APIs:

```typescript
// Inside ObsBrowserSourceApp.tsx
const eventSource = new EventSource(buildEventSourceUrl());

eventSource.onopen = () => setConnected(true);
eventSource.onerror = () => setConnected(false);

eventSource.addEventListener('config', e => setConfig(JSON.parse(e.data)));
eventSource.addEventListener('clock', e => { 
  clockRef.current = JSON.parse(e.data); 
  setPlaybackState(prev => prev === nextClock.playerState ? prev : nextClock.playerState); 
});
eventSource.addEventListener('audio', e => {
  const a = JSON.parse(e.data);
  audioPower.set(a.audioPower);
  bass.set(a.bands.bass);
  // … set other bands and spectrum …
});

```

### Handling Audio Analysis Data

The audio event delivers pre-processed frequency bands and raw spectrum data that the visualizer consumes directly:

```typescript
eventSource.addEventListener('audio', (event) => {
  const audioData = JSON.parse(event.data);
  // audioData.audioPower: number
  // audioData.bands.bass: number
  // audioData.spectrum: number[]
});

```

## Summary

- **Folia** offloads visualizer rendering to OBS via a Browser Source, reducing CPU usage in the main application.
- The integration uses **EventSource** (`/obs/events?token=…`) for real-time communication between Folia's Electron main process and the OBS browser source.
- Key files include [`useObsBrowserSourcePublisher.ts`](https://github.com/chthollyphile/folia-major/blob/main/useObsBrowserSourcePublisher.ts) for data publishing, [`ObsBrowserSourceApp.tsx`](https://github.com/chthollyphile/folia-major/blob/main/ObsBrowserSourceApp.tsx) for the OBS-side renderer, and [`obsBrowserSource.ts`](https://github.com/chthollyphile/folia-major/blob/main/obsBrowserSource.ts) for type definitions.
- Enable the feature in **IntegrationSettingsSubview**, copy the generated URL, and paste it into an OBS Browser Source.
- When connected, Folia displays a **Clients** badge and stops local visualizer rendering to optimize performance.

## Frequently Asked Questions

### Does enabling the OBS Browser Source affect Folia's performance?

Yes, but positively. When the `isObsBrowserSourceRendering` flag detects an active OBS connection, Folia stops rendering the visualizer in the main window. This frees up GPU and CPU resources for audio processing and streaming, while OBS handles the graphics rendering separately.

### What resolution should I set for the OBS Browser Source?

Set the Browser Source dimensions to match your streaming output, typically **1920×1080**. The [`ObsBrowserSourceApp.tsx`](https://github.com/chthollyphile/folia-major/blob/main/ObsBrowserSourceApp.tsx) component automatically adjusts the device-pixel-ratio to ensure crisp rendering at high resolutions, preventing the blurry scaling that occurs when capturing the Folia window directly.

### Can I use Folia normally while streaming to OBS?

Once connected, Folia continues to function as a music player and audio analyzer, but the visualizer only renders inside OBS. The main window displays a "Clients" indicator showing active connections. You can control playback, switch themes, and manage playlists—these changes sync to OBS in real-time via the EventSource connection.

### How is the connection secured between Folia and OBS?

Folia generates a unique token appended to the EventSource URL (`/obs/events?token=…`). This token is displayed in the `IntegrationSettingsSubview` UI and must be copied exactly into OBS. The local server only accepts connections presenting this token, preventing unauthorized access to your playback data.