@sndwrks/osc-cli 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# OSC CLI Tool
+
+**DISCLAIMER: this was written by AI, but it will be maintained by humans (probably)**
+
+A simple command-line application for sending and receiving OSC (Open Sound Control) messages via TCP and UDP.
+
+## Features
+
+- Listen for OSC messages via UDP
+- Listen for OSC messages via TCP
+- Listen on both protocols simultaneously
+- Send OSC messages via UDP
+- Send OSC messages via TCP
+- Logging with @sndwrks/lumberjack
+- **Installable as a global CLI tool**
+
+## Installation
+
+### Install Globally
+
+```bash
+npm install -g .
+```
+
+After installation, you can use the `osc-cli` command from anywhere:
+
+```bash
+osc-cli listen-udp 8000
+```
+
+### Install as Dependency
+
+```bash
+npm install
+```
+
+### Install from npm (if published)
+
+```bash
+npm install -g osc-cli
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Usage
+
+Once installed globally, use the `osc-cli` command. If not installed globally, use `npm start` instead.
+
+### Listen for OSC Messages
+
+**UDP (default port 57121):**
+```bash
+osc-cli listen-udp
+osc-cli listen-udp 8000
+```
+
+**TCP (default port 57122):**
+```bash
+osc-cli listen-tcp
+osc-cli listen-tcp 8001
+```
+
+**Both UDP and TCP:**
+```bash
+osc-cli listen-both
+osc-cli listen-both 8000 8001
+```
+
+### Send OSC Messages
+
+**UDP:**
+```bash
+osc-cli send-udp /test hello 123 127.0.0.1 57121
+osc-cli send-udp /synth/note 440 0.5 localhost 8000
+```
+
+**TCP:**
+```bash
+osc-cli send-tcp /test hello 123 127.0.0.1 57122
+osc-cli send-tcp /synth/note 440 0.5 localhost 8001
+```
+
+## Message Format
+
+- **Address**: OSC address pattern (e.g., `/test`, `/synth/freq`)
+- **Args**: Space-separated values (automatically parsed as numbers if possible)
+- **Host**: Target hostname or IP address (default: 127.0.0.1)
+- **Port**: Target port number
+
+## Examples
+
+```bash
+# Install globally
+npm install -g .
+
+# Start listening on UDP port 8000
+osc-cli listen-udp 8000
+
+# In another terminal, send a message
+osc-cli send-udp /hello world 127.0.0.1 8000
+
+# Listen on both protocols
+osc-cli listen-both 9000 9001
+
+# Send via TCP
+osc-cli send-tcp /synth/freq 440 127.0.0.1 9001
+```
+
+## Development
+
+If you haven't installed globally, you can use npm scripts:
+
+```bash
+npm run build          # Build TypeScript
+npm start listen-udp   # Run with npm start
+```
+
+## Uninstall
+
+```bash
+npm uninstall -g osc-cli
+```
+
+## Publishing to NPM
+
+See [PUBLISHING.md](PUBLISHING.md) for detailed instructions on how to publish this package to npm with the TypeScript build step.
+
+## Dependencies
+
+- `osc`: OSC protocol implementation
+- `@sndwrks/lumberjack`: Winston-based logging library
+
+**Note:** This package includes custom TypeScript type definitions for the `osc` library in `src/types/osc.d.ts` since the osc package doesn't provide its own types.

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { listenUDP, listenTCP, sendUDP, sendTCP, logger } from './index.js';
+// CLI Interface
+const args = process.argv.slice(2);
+const command = args[0];
+switch (command) {
+    case 'listen-udp':
+        const udpPort = parseInt(args[1]) || 57121;
+        listenUDP(udpPort);
+        break;
+    case 'listen-tcp':
+        const tcpPort = parseInt(args[1]) || 57122;
+        listenTCP(tcpPort);
+        break;
+    case 'listen-both':
+        const udpBothPort = parseInt(args[1]) || 57121;
+        const tcpBothPort = parseInt(args[2]) || 57122;
+        listenUDP(udpBothPort);
+        listenTCP(tcpBothPort);
+        logger.info('Listening on both UDP and TCP');
+        break;
+    case 'send-udp':
+        if (args.length < 2) {
+            logger.error('Usage: send-udp <address> [args...] [host] [port]');
+            process.exit(1);
+        }
+        const udpAddress = args[1];
+        const udpArgs = args.slice(2, -2).map(arg => {
+            const num = parseFloat(arg);
+            return isNaN(num) ? arg : num;
+        });
+        const udpHost = args[args.length - 2] || '127.0.0.1';
+        const udpSendPort = parseInt(args[args.length - 1]) || 57121;
+        sendUDP(udpAddress, udpArgs, udpHost, udpSendPort);
+        break;
+    case 'send-tcp':
+        if (args.length < 2) {
+            logger.error('Usage: send-tcp <address> [args...] [host] [port]');
+            process.exit(1);
+        }
+        const tcpAddress = args[1];
+        const tcpArgs = args.slice(2, -2).map(arg => {
+            const num = parseFloat(arg);
+            return isNaN(num) ? arg : num;
+        });
+        const tcpHost = args[args.length - 2] || '127.0.0.1';
+        const tcpSendPort = parseInt(args[args.length - 1]) || 57122;
+        sendTCP(tcpAddress, tcpArgs, tcpHost, tcpSendPort);
+        break;
+    default:
+        console.log(`
+OSC CLI Tool
+
+Usage:
+  osc-cli listen-udp [port]              - Listen for UDP OSC messages (default port: 57121)
+  osc-cli listen-tcp [port]              - Listen for TCP OSC messages (default port: 57122)
+  osc-cli listen-both [udpPort] [tcpPort] - Listen on both UDP and TCP
+  osc-cli send-udp <address> [args...] [host] [port] - Send OSC via UDP
+  osc-cli send-tcp <address> [args...] [host] [port] - Send OSC via TCP
+
+Examples:
+  osc-cli listen-udp 8000
+  osc-cli listen-both 8000 8001
+  osc-cli send-udp /test hello 123 127.0.0.1 8000
+  osc-cli send-tcp /synth/freq 440 localhost 8001
+    `);
+        break;
+}

package/dist/index.js

@@ -0,0 +1,116 @@
+import osc from 'osc';
+import { beginLogging, configureLogger } from '@sndwrks/lumberjack';
+// Configure logger globally
+configureLogger({
+    logToConsole: {
+        enabled: true,
+        type: 'pretty'
+    },
+    logLevel: 'info',
+    service: 'osc-cli'
+});
+// Create logger instance
+const logger = beginLogging({ name: 'OSC-CLI' });
+/**
+ * Listen for OSC messages via UDP
+ */
+export function listenUDP(port = 57121) {
+    const udpPort = new osc.UDPPort({
+        localAddress: '0.0.0.0',
+        localPort: port,
+        metadata: true
+    });
+    udpPort.on('ready', () => {
+        logger.info(`Listening for OSC over UDP on port ${port}`);
+    });
+    udpPort.on('message', (oscMsg) => {
+        logger.info('UDP OSC message received:', {
+            address: oscMsg.address,
+            args: oscMsg.args
+        });
+    });
+    udpPort.on('error', (err) => {
+        logger.error('UDP Error:', err);
+    });
+    udpPort.open();
+    return udpPort;
+}
+/**
+ * Listen for OSC messages via TCP
+ */
+export function listenTCP(port = 57122) {
+    const tcpPort = new osc.TCPSocketPort({
+        localAddress: '0.0.0.0',
+        localPort: port,
+        metadata: true
+    });
+    tcpPort.on('ready', () => {
+        logger.info(`Listening for OSC over TCP on port ${port}`);
+    });
+    tcpPort.on('message', (oscMsg) => {
+        logger.info('TCP OSC message received:', {
+            address: oscMsg.address,
+            args: oscMsg.args
+        });
+    });
+    tcpPort.on('error', (err) => {
+        logger.error('TCP Error:', err);
+    });
+    tcpPort.open();
+    return tcpPort;
+}
+/**
+ * Send OSC message via UDP
+ */
+export function sendUDP(address, args, host = '127.0.0.1', port = 57121) {
+    const udpPort = new osc.UDPPort({
+        localAddress: '0.0.0.0',
+        localPort: 0,
+        metadata: true
+    });
+    udpPort.on('ready', () => {
+        logger.info(`Sending OSC message via UDP to ${host}:${port}`);
+        udpPort.send({
+            address: address,
+            args: args
+        }, host, port);
+        logger.info('Message sent:', { address, args });
+        // Close after sending
+        setTimeout(() => {
+            udpPort.close();
+        }, 100);
+    });
+    udpPort.on('error', (err) => {
+        logger.error('UDP Send Error:', err);
+    });
+    udpPort.open();
+}
+/**
+ * Send OSC message via TCP
+ */
+export function sendTCP(address, args, host = '127.0.0.1', port = 57122) {
+    const tcpPort = new osc.TCPSocketPort({
+        localAddress: '0.0.0.0',
+        localPort: 0,
+        remoteAddress: host,
+        remotePort: port,
+        metadata: true
+    });
+    tcpPort.on('ready', () => {
+        logger.info(`Sending OSC message via TCP to ${host}:${port}`);
+        tcpPort.send({
+            address: address,
+            args: args
+        });
+        logger.info('Message sent:', { address, args });
+        // Close after sending
+        setTimeout(() => {
+            tcpPort.close();
+        }, 100);
+    });
+    tcpPort.on('error', (err) => {
+        logger.error('TCP Send Error:', err);
+    });
+    tcpPort.open();
+}
+export { logger };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@sndwrks/osc-cli",
+  "version": "1.0.0",
+  "description": "Simple OSC command-line tool",
+  "keywords": [
+    "osc",
+    "cli",
+    "tcp",
+    "udp",
+    "open-sound-control"
+  ],
+  "homepage": "https://github.com/sndwrks/osc-cli#readme",
+  "bugs": {
+    "url": "https://github.com/sndwrks/osc-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sndwrks/osc-cli.git"
+  },
+  "license": "MIT",
+  "author": "john mckenna",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "osc-cli": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@sndwrks/lumberjack": "^0.8.0",
+    "osc": "^2.4.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}