Forem: Gustavo Henrique

How to Receive Video Position Feedback from MadMapper using Node.js OSC

Gustavo Henrique — Wed, 17 Sep 2025 05:13:18 +0000

A comprehensive guide to receiving real-time video playback position feedback from MadMapper using Node.js and OSC (Open Sound Control) protocol.

Introduction
Prerequisites
Understanding OSC Feedback in MadMapper
Setting Up the Node.js Monitor
MadMapper Configuration
Complete Example
Troubleshooting
Advanced Use Cases

Introduction

This guide demonstrates how to receive real-time video position feedback from MadMapper using Node.js and OSC. You'll learn to capture video playback progress and trigger actions when videos reach specific points (like the end). This is particularly useful for interactive installations, live performances, or automated content management systems.

Why this guide exists:
While researching MadMapper OSC integration, I found scattered information in forums and documentation about OSC feedback, but nothing comprehensive about implementing this with Node.js. Most existing resources focus on dedicated OSC applications like TouchOSC, Chataigne, or QLab - software that handles OSC natively. This guide fills that gap by showing how to build custom Node.js applications that can receive and process MadMapper's video feedback.

What you'll learn:

How OSC feedback works in MadMapper
Setting up Node.js to receive OSC feedback from MadMapper
Capturing video position updates in real-time
Processing feedback data to trigger automated actions

Prerequisites

MadMapper (any recent version)
Node.js installed on your system
Basic understanding of JavaScript
Videos loaded in MadMapper

Understanding OSC Feedback in MadMapper

Key Concept: Manual Control Mapping

Important: MadMapper only sends OSC feedback for manually created controls, not for predefined OSC channels.

❌ Won't work: Direct feedback from /surfaces/Quad-1/opacity
✅ Will work: Manual control mapping /myVideo → /medias/video.mp4/position

How OSC Feedback Works

You create a manual OSC control in MadMapper
You map this control to a video parameter (like position)
MadMapper sends feedback to your OSC address when the parameter changes
Your Node.js app receives and processes this feedback

Setting Up Node.js to Receive OSC Feedback

Installation

First, install the required OSC library:

npm install node-osc

Basic OSC Server Setup

const osc = require("node-osc");

// Configuration
const MADMAPPER_IP = "127.0.0.1";  // MadMapper's IP
const MADMAPPER_PORT = 8010;       // MadMapper's OSC input port
const FEEDBACK_PORT = 8011;        // Port to receive feedback

// Create OSC server to receive feedback
const server = new osc.Server(FEEDBACK_PORT, "0.0.0.0");
console.log(`OSC Server listening on port ${FEEDBACK_PORT}`);

// Create OSC client to send commands
const client = new osc.Client(MADMAPPER_IP, MADMAPPER_PORT);

Receiving Video Position Updates

// Track video states
const videoStates = {
  "/video/intro": {
    position: 0,
    hasFinished: false,
    displayName: "Intro Video"
  },
  "/video/main": {
    position: 0,
    hasFinished: false,
    displayName: "Main Content"
  }
};

// Handle incoming OSC messages
server.on("message", (msg, rinfo) => {
  const [address, ...args] = msg;
  const position = args[0]; // 0.0 to 1.0

  console.log(`VIDEO ${address}: ${(position * 100).toFixed(1)}%`);

  // Check if this is a monitored video
  if (videoStates[address]) {
    const oldPosition = videoStates[address].position;
    videoStates[address].position = position;

    // Detect video end (99.5% or more)
    // Note: We use 0.995 instead of 1.0 because video position
    // rarely reaches exactly 100% in practice
    if (position >= 0.995 && !videoStates[address].hasFinished) {
      console.log(`VIDEO ${videoStates[address].displayName} finished!`);
      videoStates[address].hasFinished = true;

      // Trigger your action here
      triggerNextAction(address);
    }

    // Reset when video restarts
    if (position < 0.1 && videoStates[address].hasFinished) {
      videoStates[address].hasFinished = false;
      console.log(`VIDEO ${videoStates[address].displayName} restarted`);
    }
  }
});

function triggerNextAction(videoAddress) {
  // Example: Start another video or trigger an effect
  console.log("Triggering next action...");
  client.send("/nextVideo", 1);
}

MadMapper Configuration

Step 1: OSC Preferences

Open MadMapper Preferences
Go to OSC section
Set:
- OSC Input Port: 8010
- Feedback Mode: Auto or Manual
- Feedback IP: Auto (or your computer's IP)
- Feedback Port: 8011

Step 2: Create Manual OSC Controls

This is crucial for feedback to work!

Open Window → Controls
Click "+" to add new control
Select OSC type
Configure:
- OSC Address: /video/intro (your custom address)
- Target: Click "Learn" and move the video position slider
- OR manually type: /medias/your-video-file.mp4/position
- Handle Feedback: checked

Screenshot of MadMapper Controls window showing multiple video position controls configured with OSC addresses (/medias/videoX.mp4/position) and the Enable Feedback option checked. This is the essential setup for receiving real-time position updates from video playback.

Step 3: Register Your Application

Send an initial message to register with MadMapper:

// Register with MadMapper (Auto mode)
client.send("/ping", 1, () => {
  console.log("Registered with MadMapper");
});

Complete Example

Here's a complete working example:

const osc = require("node-osc");

class VideoMonitor {
  constructor() {
    this.MADMAPPER_IP = "127.0.0.1";
    this.MADMAPPER_PORT = 8010;
    this.FEEDBACK_PORT = 8011;

    this.setupOSC();
    this.setupVideoStates();
    this.registerWithMadMapper();
  }

  setupOSC() {
    // OSC server for receiving feedback
    this.server = new osc.Server(this.FEEDBACK_PORT, "0.0.0.0");
    this.server.on("message", this.handleOSCMessage.bind(this));

    // OSC client for sending commands
    this.client = new osc.Client(this.MADMAPPER_IP, this.MADMAPPER_PORT);

    console.log(`OSC Monitor ready on port ${this.FEEDBACK_PORT}`);
  }

  setupVideoStates() {
    this.videos = {
      "/video/intro": { position: 0, finished: false, name: "Intro" },
      "/video/main": { position: 0, finished: false, name: "Main Content" },
      "/video/outro": { position: 0, finished: false, name: "Outro" }
    };
  }

  registerWithMadMapper() {
    setTimeout(() => {
      this.client.send("/ping", 1);
      console.log("Registered with MadMapper");
    }, 1000);
  }

  handleOSCMessage(msg, rinfo) {
    const [address, position] = msg;

    if (this.videos[address]) {
      this.updateVideoState(address, position);
    }
  }

  updateVideoState(address, position) {
    const video = this.videos[address];
    const oldPosition = video.position;
    video.position = position;

    const percent = (position * 100).toFixed(1);
    console.log(`VIDEO ${video.name}: ${percent}%`);

    // Check for video completion (99.5% threshold)
    // Using 0.995 instead of 1.0 because videos rarely reach exactly 100%
    if (position >= 0.995 && !video.finished) {
      this.onVideoFinished(address, video);
    }

    // Reset on restart
    if (position < 0.1 && video.finished) {
      video.finished = false;
      console.log(`VIDEO ${video.name} restarted`);
    }
  }

  onVideoFinished(address, video) {
    console.log(`VIDEO ${video.name} FINISHED!`);
    video.finished = true;

    // Add your custom logic here
    switch(address) {
      case "/video/intro":
        this.startMainVideo();
        break;
      case "/video/main":
        this.startOutroVideo();
        break;
      case "/video/outro":
        this.loopToIntro();
        break;
    }
  }

  startMainVideo() {
    console.log("Starting main video...");
    this.client.send("/video/main", 1);
  }

  startOutroVideo() {
    console.log("Starting outro video...");
    this.client.send("/video/outro", 1);
  }

  loopToIntro() {
    console.log("Looping back to intro...");
    setTimeout(() => {
      this.client.send("/video/intro", 1);
    }, 2000);
  }

  // Status reporting
  printStatus() {
    console.log("\nVIDEO STATUS:");
    Object.entries(this.videos).forEach(([addr, video]) => {
      const percent = (video.position * 100).toFixed(1);
      const status = video.finished ? "Finished" : "Playing";
      console.log(`  ${video.name}: ${percent}% - ${status}`);
    });
    console.log("");
  }
}

// Start the monitor
const monitor = new VideoMonitor();

// Show status every 10 seconds
setInterval(() => monitor.printStatus(), 10000);

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('\nShutting down video monitor...');
  process.exit(0);
});

Important Notes

Why 99.5% Instead of 100%?

In practice, video position values in MadMapper rarely reach exactly 1.0 (100%). This is common in many video playback systems due to:

Frame timing precision: Video frames don't align perfectly with percentage calculations
Buffering behavior: The last few milliseconds might not trigger position updates
Codec specifics: Different video formats handle end-of-stream differently

Using 0.995 (99.5%) as the threshold ensures reliable detection of video completion while still being close enough to the actual end.

Troubleshooting

Common Issues

Not receiving any OSC messages

Verify MadMapper OSC preferences (IP addresses and port numbers)
Ensure you created manual OSC controls with "Handle Feedback" checked
Send a ping message to register with MadMapper (required for Auto mode)
Check firewall settings that might block OSC communication

Receiving only 0 or 1 values (not gradual position)

Your OSC control is likely mapped to play/stop instead of position
Re-map the control target to /medias/[filename]/position
Use the "Learn" function while manually moving the video position slider
Verify the control is mapped to the timeline position, not play button

Feedback stops working after MadMapper restart

Re-send the ping message to re-register your application
Check if "Auto" feedback mode lost your application in its registry
Verify OSC preferences weren't reset during restart

Debug Tips

// Add detailed debugging
server.on("message", (msg, rinfo) => {
  console.log(`OSC Debug:`);
  console.log(`   From: ${rinfo.address}:${rinfo.port}`);
  console.log(`   Address: "${msg[0]}"`);
  console.log(`   Value: ${msg[1]} (${typeof msg[1]})`);
  console.log(`   Raw:`, msg);
});

Advanced Use Cases

Multiple Video Synchronization

Monitor multiple videos and ensure they stay synchronized:

// Check if videos are in sync (within 5% tolerance)
const tolerance = 0.05;
const positions = Object.values(videos).map(v => v.position);
const minPos = Math.min(...positions);
const maxPos = Math.max(...positions);

if (maxPos - minPos > tolerance) {
  console.log("Videos out of sync!");
  // Implement sync logic
}

Dynamic Video Switching

Create playlists that automatically advance:

const playlist = ["/video/intro", "/video/main", "/video/outro"];
let currentIndex = 0;

function playNext() {
  if (currentIndex < playlist.length - 1) {
    currentIndex++;
    client.send(playlist[currentIndex], 1);
  } else {
    // Loop back to start
    currentIndex = 0;
    client.send(playlist[currentIndex], 1);
  }
}

Performance Analytics

Track video performance metrics:

const analytics = {
  completionRates: {},
  averageWatchTime: {},
  skipPoints: {}
};

// Track when users skip videos
function trackSkip(address, position) {
  if (!analytics.skipPoints[address]) {
    analytics.skipPoints[address] = [];
  }
  analytics.skipPoints[address].push(position);
}

Conclusion

This guide bridges the gap between MadMapper's OSC capabilities and Node.js development, providing a practical foundation for receiving video position feedback. While most OSC resources focus on dedicated applications, this approach enables custom JavaScript solutions for unique project requirements.

The key insights are:

Manual control creation is essential for OSC feedback
Position values range from 0.0 to 1.0
Registration with MadMapper enables feedback in Auto mode
Real-time feedback enables reactive content systems

With these techniques, you can create sophisticated interactive video installations, automated content management systems, and responsive multimedia experiences that go beyond what traditional OSC applications offer.

Bridging Madmapper and Web: A Real-world Integration Story Guide

Gustavo Henrique — Mon, 24 Feb 2025 05:16:40 +0000

I recently faced a challenge when trying to connect Madmapper to a web application. Since Madmapper only accepts OSC (Open Sound Control) messages, integrating it directly with today's web and mobile technologies was tricky. To overcome this limitation, I built a workaround using Firebase and Node.js and I'm sharing this guide in case anyone else runs into the same problem.

The Problem

Madmapper excels in projection mapping but communicates solely via OSC messages. OSC is fantastic for real-time performance environments, yet it doesn't play well with HTTP-based web or mobile applications.

In my case, the task was to control Madmapper from an Android app on a tablet during a museum presentation. I needed a way to bridge the gap between a web-based interface (and the mobile app that drives it) and Madmapper's OSC-only input.

Finding the Right Solution

After exploring various options, I landed on a combination that worked surprisingly well:

Firebase as a real-time message broker
Node.js server as a protocol translator
Simple web interface for control
OSC messages for final communication

This setup solved several key challenges:

Real-time control requirements
Multiple device support
Reliable message delivery
User-friendly interface

The Implementation

Here's how I put it all together:

1. Setting Up the Bridge

First, I created a Node.js server that would act as our translator:

const express = require('express');
const bodyParser = require('body-parser');
const path = require('path');
const osc = require('node-osc');
const { initializeApp } = require('firebase/app');
const { getDatabase, ref, onValue } = require('firebase/database');

// Initialize Firebase and OSC client
const app = initializeApp(firebaseConfig);
const database = getDatabase(app);
const oscClient = new osc.Client(getLocalIpAddress(), 8010);

2. Creating the Communication Flow

The system works in three main steps:

Step 1: Web interface sends command

async function assignVideo(videoId) {
  await fetch('/assign-video', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ videoId })
  });
}

Step 2: Server updates Firebase

app.post('/assign-video', async (req, res) => {
  const { videoId } = req.body;
  await set(ref(database, 'currentVideo'), {
    playVideo: true,
    videoId
  });
  res.json({ success: true });
});

Step 3: Firebase listener sends OSC

onValue(ref(database, 'currentVideo'), async (snapshot) => {
  const data = snapshot.val();
  if (data?.playVideo) {
    await sendOSCMessage(videoOscMap[data.videoId], 1);
  }
});

Network Matters

Some key considerations for network stability:

Local network stability is crucial
Always implement error handling for network issues
Provide clear feedback when communication fails

Here's an example of robust error handling:

async function sendOSCMessage(address, value) {
  try {
    await new Promise((resolve, reject) => {
      oscClient.send(address, value, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
    console.log(`OSC message sent successfully to ${address}`);
  } catch (error) {
    console.error(`Failed to send OSC message: ${error.message}`);
    throw error;
  }
}

Conclusion

This solution has been running successfully in production for several months now. While it might seem like a complex setup at first, it's actually quite straightforward once you understand the pieces involved. The key is to keep the implementation simple and focused on reliability.

For those interested in trying this approach, I've made the complete code available on GitHub. Feel free to adapt it to your needs or suggest improvements.

Questions or suggestions? Feel free to reach out through GitHub issues or comments below.

How to Build an Icon Library with TypeScript, Tsup, and SVGR

Gustavo Henrique — Fri, 27 Sep 2024 21:25:02 +0000

Want to create an icon library for your React project with TypeScript? With Tsup and SVGR, you can efficiently turn SVG files into reusable React components. Let’s go straight to the point and build this from scratch.

Project Folder Structure

Before diving in, here’s the folder structure we’re aiming for:

my-icons-library/
├── icons/                  # SVG files go here
├── src/
│   └── icons/              # Generated React components
├── scripts/                # Utility scripts for custom tasks
├── index.ts                # Entry point of the library
├── tsconfig.json           # TypeScript config file
├── package.json            # Project settings
└── tsup.config.ts          # Tsup config file for building the project

Step 1: Setting Up the Project

First, create a new folder, initialize the project, and install dependencies:

mkdir my-icons-library
cd my-icons-library
npm init -y
npm install react react-dom typescript tsup @svgr/cli @types/react @types/react-dom svgo --save-dev

This sets up your React environment with TypeScript, SVGR, and Tsup for bundling.

Step 2: Configuring TypeScript

Let’s configure TypeScript. Create a tsconfig.json file and add the following content:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "jsx": "react-jsx",
    "declaration": true,
    "declarationDir": "dist/types",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "skipLibCheck": true,
    "isolatedModules": true
  },
  "include": ["src/**/*", "scripts/*", "index.ts"],
  "exclude": ["node_modules", "dist"]
}

This config ensures TypeScript compiles the icons into proper .d.ts type definitions and outputs the compiled code in the dist folder.

Step 3: Generating Icons with SVGR

Now, let’s turn your SVG files into React components with SVGR. Add the following script to your package.json:

"scripts": {
  "generate-icons": "npx @svgr/cli --typescript --icon --out-dir src/icons icons"
}

Run the command to transform all SVGs in the icons/ folder into React components inside src/icons/:

npm run generate-icons

Step 4: Customizing Icons (Size & Color)

You’ll likely want to modify your icons to allow dynamic sizing and coloring. Create a script called modify-icons.ts in the scripts/ folder:

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const ICONS_DIR = path.join(__dirname, '..', 'src', 'icons');

const modifyIcon = (filePath: string) => {
  let content = fs.readFileSync(filePath, 'utf-8');

  const propsRegex = /SVGProps<SVGSVGElement>/;
  if (propsRegex.test(content)) {
    content = content.replace(
      propsRegex,
      `(SVGProps<SVGSVGElement> & { size?: string | number; color?: string })`
    );
  }

  const svgTagRegex = /<svg([^>]*)>/;
  const svgMatch = content.match(svgTagRegex);
  if (svgMatch) {
    const svgAttributes = svgMatch[1];

    let newSvgAttributes = svgAttributes
      .replace(/width="[^"]*"/, '{...(props.size ? { width: props.size, height: props.size } : { width: "1em", height: "1em" })}')
      .replace(/height="[^"]*"/, '');

    newSvgAttributes += ' fill={props.color || "currentColor"}';

    content = content.replace(svgTagRegex, `<svg${newSvgAttributes}>`);
  }

  fs.writeFileSync(filePath, content, 'utf-8');
};

const main = () => {
  fs.readdir(ICONS_DIR, (err, files) => {
    if (err) {
      console.error('Error reading icons directory:', err);
      process.exit(1);
    }

    files.forEach((file) => {
      const filePath = path.join(ICONS_DIR, file);
      if (path.extname(file) === '.tsx') {
        try {
          modifyIcon(filePath);
          console.log(`Modified: ${file}`);
        } catch (error) {
          console.error(`Error modifying ${file}:`, error);
        }
      }
    });
  });
};

main();

Run this script after generating the icons to add dynamic size and color properties to your components.

Step 5: Automatically Exporting Icons

To avoid manually exporting each icon, create a script called generate-index.ts in the scripts/ folder that will auto-generate an index.ts file for all your icons:

import { readdirSync, writeFileSync } from 'fs';
import { resolve, join, basename } from 'path';

const iconsDir = resolve('src/icons');
const indexPath = join(resolve(), 'index.ts');

const files = readdirSync(iconsDir).filter((file) => file.endsWith('.tsx'));

const exportStatements = files
  .map((file) => {
    const componentName = basename(file, '.tsx');
    return `export { default as ${componentName} } from './src/icons/${componentName}';`;
  })
  .join('\n');

writeFileSync(indexPath, exportStatements);

console.log(`Generated index.ts with ${files.length} icon exports.`);

Run this script to generate the index.ts file with exports for all your icons.

Step 6: Bundling with Tsup

Now it’s time to bundle the project using Tsup. Create a tsup.config.ts file:

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['index.ts'],
  outDir: 'dist',
  format: ['cjs', 'esm'],
  dts: true,
  splitting: true,
  sourcemap: true,
  clean: true,
  external: ['react', 'react-dom'],
});

Add the following script to your package.json:

"scripts": {
  "build": "tsup"
}

Run the build command:

npm run build

Your icon library is now bundled and ready to be used!

Step 7: Configuring the `package.json`

Here’s how your package.json should look like for publishing your library to npm:

{
  "name": "my-icons-library",
  "version": "1.0.0",
  "description": "A TypeScript React icon library",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist",
    "src"
  ],
  "scripts": {
    "start": "vite",
    "generate-icons": "npx @svgr/cli --typescript --icon --out-dir src/icons icons",
    "generate-and-modify-icons": "npm run generate-icons && node scripts/modify-icons.ts",
    "build": "tsup",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "tsup": "^5.0.0",
    "@svgr/cli": "^5.0.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}

This package.json setup ensures that your library is packaged correctly and ready for npm publishing.

Step 8: Publishing to npm

Here’s how you can publish your icon library to npm:

1. Create an npm account

If you don’t already have one, create an account on npm.

2. Log in via the terminal

In your project’s root directory, log in to npm:

npm login

3. Publish your package

Once logged in, you can publish your library to npm:

npm publish --access public

This command will upload your package to the npm registry, and it will be available for others to install and use.

Conclusion

By following these steps, you’ve created a fully functional icon library with TypeScript, SVGR, and Tsup. Your icons are now reusable, customizable React components, and you’ve learned how to publish them to npm for the world to use.

I hope you found this guide helpful! If you'd like to see the full repository, feel free to check it out at https://github.com/avoguga/icon-library-template.

For those looking to deepen their understanding of how to create and publish a TypeScript library, I highly recommend checking out the following articles:

How to Create a React Component Library Using Vite’s Library Mode – A great guide on building a tree shakeable React component library with Vite’s library mode.
How to Write a Tree-Shakable Component Library.

Additionally, if you're interested in learning more about how to bundle a tree-shakable TypeScript library using Tsup, I recommend this detailed guide:

How to Bundle a Tree-Shakable TypeScript Library with Tsup and Publish with npm

These resources will offer you a broader perspective on the best practices and techniques for building and distributing libraries efficiently.

Forem: Gustavo Henrique

How to Receive Video Position Feedback from MadMapper using Node.js OSC

Table of Contents

Introduction

Prerequisites

Understanding OSC Feedback in MadMapper

Key Concept: Manual Control Mapping

How OSC Feedback Works

Setting Up Node.js to Receive OSC Feedback

Installation

Basic OSC Server Setup

Receiving Video Position Updates

MadMapper Configuration

Step 1: OSC Preferences

Step 2: Create Manual OSC Controls

Step 3: Register Your Application

Complete Example

Important Notes

Why 99.5% Instead of 100%?

Troubleshooting

Common Issues

Debug Tips

Advanced Use Cases

Multiple Video Synchronization

Dynamic Video Switching

Performance Analytics

Conclusion

Bridging Madmapper and Web: A Real-world Integration Story Guide

The Problem

Finding the Right Solution

The Implementation

1. Setting Up the Bridge

2. Creating the Communication Flow

Network Matters

Conclusion

How to Build an Icon Library with TypeScript, Tsup, and SVGR

Project Folder Structure

Step 1: Setting Up the Project

Step 2: Configuring TypeScript

Step 3: Generating Icons with SVGR

Step 4: Customizing Icons (Size & Color)

Step 5: Automatically Exporting Icons

Step 6: Bundling with Tsup

Step 7: Configuring the package.json

Step 8: Publishing to npm

1. Create an npm account

2. Log in via the terminal

3. Publish your package

Conclusion

Step 7: Configuring the `package.json`