010 - StudioLink

StudioLink is the real-time communication system via sockets.

The Idea

You're working on an artwork, tweaking Tweakpane settings – and all these changes appear live in Art.Works! Studio. You see parameter values, can trigger snapshots, control the animation. All in real-time, without reload.

StudioLink makes this possible. It's a bidirectional channel between artworks and Studio, based on sockets.

Core Functions:

Parameter Synchronization – Tweakpane values live to Studio and back
Artwork State – Which agents are active? What does the SceneGraph look like?
Snapshots on Demand – Studio asks, artwork delivers screenshot
Logging – Console.log ends up in Studio instead of browser DevTools

Extended Visions (in development):

Artworks communicate with each other (shape exits right from Artwork A, appears left in Artwork B)
External data sources (weather APIs, sensors) feed into artworks
Control robots/plotters via StudioLink

Architecture

┌─────────────────────────────────────────┐
│           Studio (Electron)             │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │   Socket    │  │ Studio Renderer │   │
│  │   Server    │  │                 │   │
│  │  Port 3090  │  └────────┬────────┘   │
│  └──────┬──────┘           │            │
│         │    ┌─────────────┘            │
│         │    │   ┌──────────────────┐   │
│         │    │   │  Studio Backend  │   │
│         │    │   └────────┬─────────┘   │
└─────────┼────┼────────────┼─────────────┘
          │    │            │
    ┌─────┴────┴────────────┴─────┐
    │                             │
┌───┴───┐   ┌─────────┐   ┌───────┴───┐
│Artwork│   │ Artwork │   │  Artwork  │
│   1   │   │    2    │   │     3     │
│webview│   │ webview │   │  Browser  │
└───────┘   └─────────┘   └───────────┘

Components

Class	File	Function
`StudioSocketAPI`	`StudioSocketAPI.ts`	Low-level Socket Wrapper
`StudioLinkManager`	`StudioLinkManager.ts`	High-level Manager

Room Structure

Room	Description	Members
`studio`	Studio UI	Studio Renderer
`artwork:{id}`	Specific Artwork	Artwork + Studio (Observer)
`backend`	Backend Services	Backend Process
`logs`	Central Log Channel	All

Message Types

Logs

type LogMessage = {
  type: 'log';
  level: 'debug' | 'info' | 'warn' | 'error';
  component: string;
  message: string;
  timestamp: string;
  metadata?: any;
};

Control Commands (Studio → Artwork)

Type	Description
`request-parameter-dump`	Request Parameters
`apply-parameter`	Change Parameter
`request-snapshot`	Request Screenshot
`control-animation`	Play/Pause/Reset

Data Messages (Artwork → Studio)

Type	Description
`parameter-dump`	Complete ParameterObject
`parameter-update`	Single Change
`snapshot-data`	Canvas as Base64
`artwork-state`	Agents, Scene Structure

StudioSocketAPI

Low-level socket wrapper.

Configuration:

Option	Type	Default	Description
`serverUrl`	`string`	'http://localhost:3090'	Server URL
`artworkId`	`string`	-	Artwork Identification
`autoConnect`	`boolean`	true	Auto-Connect?
`reconnection`	`boolean`	true	Reconnect on Disconnect?

API:

Method	Description
`connect()`	Establish Connection
`disconnect()`	Disconnect
`emit(event, data)`	Send Event
`on(event, handler)`	Register Event Handler
`joinRoom(room)`	Join Room
`leaveRoom(room)`	Leave Room

StudioLinkManager

High-level manager with auto-detect and Tweakpane support.

Features:

Auto-Detect Server
Parameter Sync
Tweakpane Integration
Auto-Send on Changes
Snapshot Handling

Configuration:

Option	Type	Default	Description
`artworkId`	`string`	-	Artwork ID
`autoSync`	`boolean`	true	Auto-Sync Parameters
`syncInterval`	`number`	100	Sync Interval (ms)
`enableLogs`	`boolean`	true	Send Logs to Server

API:

Method	Description
`init(parameter)`	Initialize
`syncParameter()`	Manual Sync
`sendSnapshot(canvas)`	Send Screenshot
`requestParameter()`	Request Parameters

Data Flow

  Artwork          StudioLink       Socket Server      Studio UI
     │                 │                  │                │
     │ Parameter       │                  │                │
     │ changed         │                  │                │
     │────────────────>│                  │                │
     │                 │ parameter-update │                │
     │                 │─────────────────>│                │
     │                 │                  │ broadcast to   │
     │                 │                  │ studio room    │
     │                 │                  │───────────────>│
     │                 │                  │                │ Update
     │                 │                  │                │ Inspector
     │                 │                  │                │
     │                 │                  │ apply-parameter│
     │                 │                  │<───────────────│
     │                 │ to artwork:{id}  │                │
     │                 │<─────────────────│                │
     │ Update local    │                  │                │
     │<────────────────│                  │                │
     │                 │                  │                │

Auto-Detect

StudioLinkManager automatically detects:

URL Parameter: ?studio=http://...
Localhost: Tries localhost:3090
Electron: Detects webview context

Snapshot System

   Studio              Server              Artwork
     │                   │                   │
     │ request-snapshot  │                   │
     │──────────────────>│                   │
     │                   │ request-snapshot  │
     │                   │──────────────────>│
     │                   │                   │ canvas.toDataURL()
     │                   │                   │
     │                   │ snapshot-data     │
     │                   │<──────────────────│
     │ snapshot-data     │   (base64)        │
     │<──────────────────│                   │
     │                   │                   │
     │ Display/Save      │                   │
     │                   │                   │

Extended Visions

Currently implemented:

Parameter Synchronization
Snapshot Transfer
Logging

Planned:

Artworks communicate with each other
Shape disappears right → appears left in the next frame
External Data Sources (Weather, APIs)
Robot/Plotter Control

The Socket Server

The server is the central hub – it routes messages between all participants.

Where does it run?

Context	Description
In Studio	Art.Works! Studio has an integrated server (Port 3090)
Standalone	`apps/node-collab-server` for tests without Studio
Docker	`apps/node-collab-server-docker` for production

The Room Concept:

Socket "rooms" group connections. An artwork joins the room artwork:001. The Studio joins all artwork rooms as an observer. This way, Studio can monitor all artworks and send messages specifically to individual artworks.

┌─────────────────────────┐  ┌─────────────────────────┐
│    Room: artwork:001    │  │    Room: artwork:002    │
│  ┌───────────────────┐  │  │  ┌───────────────────┐  │
│  │   Artwork 001     │  │  │  │   Artwork 002     │  │
│  └───────────────────┘  │  │  └───────────────────┘  │
│  ┌───────────────────┐  │  │  ┌───────────────────┐  │
│  │ Studio (Observer) │  │  │  │ Studio (Observer) │  │
│  └───────────────────┘  │  │  └───────────────────┘  │
└─────────────────────────┘  └─────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                    Room: logs                       │
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐  │
│  │ Artwork 001 │ │ Artwork 002 │ │    Studio     │  │
│  └─────────────┘ └─────────────┘ └───────────────┘  │
└─────────────────────────────────────────────────────┘

Server Events:

Event	Description
`connection`	New Client Connected
`disconnect`	Client Disconnected
`join-room`	Client Joins Room
`leave-room`	Client Leaves Room
`message`	Forward Message to Room

Usage

// In the Artwork
import { StudioLinkManager } from '@carstennichte/cc-toolbox';

const studioLink = new StudioLinkManager({
  artworkId: 'my-artwork-001',
  autoSync: true
});

studioLink.init(parameter);