osc-cli

DISCLAIMER: this was written by AI, and promptly rewritten, 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 including load testing.

What does it do?

• 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
• Load Testing with UDP
• Load Testing with TCP
• Integration Testing with UDP (send to app, validate response)
• Integration Testing with TCP (send to app, validate response)

Installation

Install from npm

npm install -g @sndwrks/osc-cli

Install from Github

# clone the repo
git clone [email protected]:sndwrks/osc-cli.git

# install globally
npm i -g .

# otherwise build and run locally
npm i
npm run build
npm start -- <commands>

Uninstall

npm uninstall -g osc-cli

Usage

Once installed globally, use osc-cli <command>. If not installed globally, use npm start -- <command> instead.

Listen for OSC Messages

Starts a server to listen for incoming OSC messages.

Args

| Flag | Option | Type | Description | Example | Default | |------|--------|------|-------------|---------|---------| | -i | --ip-address <ip-address> | string | IP address to bind to | 127.0.0.1 | 0.0.0.0 | | -p | --port <port> | number | Port the server listens on | 53000 | 51000 |

UDP (default port 51000):

osc-cli listen-udp
osc-cli listen-udp -p 8000
osc-cli listen-udp --port 8000 --ip-address 127.0.0.1

TCP (default port 51001):

osc-cli listen-tcp
osc-cli listen-tcp -p 8001
osc-cli listen-tcp --port 8001 --ip-address 127.0.0.1

Both UDP and TCP:

osc-cli listen-both
osc-cli listen-both --udp-port 8000 --tcp-port 8001
osc-cli listen-both --udp-port 8000 --tcp-port 8001 --udp-ip-address 127.0.0.1 --tcp-ip-address 127.0.0.1

Send OSC Messages

Send a single OSC message.

Args

Sends a single OSC message via UDP

| Flag | Option | Type | Description | Example | Default | |------|--------|------|-------------|---------|---------| | | --udp-ip-address <udp-ip-address> | string | IP address to bind the UDP server to | 127.0.0.1 | | | | --udp-port <udp-port> | number | Port the UDP server will listen on | 53000 | 51000 | | | --tcp-ip-address <tcp-ip-address> | string | IP address to bind the TCP server to | 127.0.0.1 | 0.0.0.0 | | | --tcp-port <tcp-port> | number | Port the TCP server will listen on | 53001 | 51001 |

UDP:

# no args
osc-cli send-udp -a /test -i 127.0.0.1 -p 57121

# with args
osc-cli send-udp -a /test -i 127.0.0.1 -p 57121 --args hello 123
osc-cli send-udp --address /synth/note --ip-address localhost --port 8000 --args 440 0.5

TCP:

osc-cli send-tcp -a /test -i 127.0.0.1 -p 57122 --args hello 123
osc-cli send-tcp --address /synth/note --ip-address localhost --port 8001 --args 440 0.5

Load Testing

The load testing allows for sending multiple messages in batches. The batches may overlap if the message rate is slower than the batch interval.

Args

| Flag | Option | Type | Required | Description | Example | Default | |------|--------|------|----------|-------------|---------|---------| | | --local-ip-address <local-ip-address> | string | No | Local IP Address to bind the client to | | 0.0.0.0 | | | --local-port <local-port> | number | No | Local port to bind the client to | | 51000 | | | --remote-ip-address <remote-ip-address> | string | Yes | IP Address to send the messages to | 10.10.209.5 | | | | --remote-port <remote-port> | number | Yes | Port to send the messages to | | | | | --messages-per-batch <messages-per-batch> | number | Yes | The number of messages per batch to send | | | | | --message-rate <message-rate> | number | No | The number of messages to send per second | | | | | --total-batches <total-batches> | number | Yes | The total number of batches to send | | | | | --batch-interval <batch-interval> | number | Yes | The time in seconds between batches | | | | | --custom-address <custom-address> | string | No | A custom address to send | | /sndwrks/osc-cli-load-tester/test |

UDP Load Test:

# minimal required args
osc-cli osc-load-test-udp \
  --remote-ip-address 127.0.0.1 \
  --remote-port 8000 \
  --messages-per-batch 100 \
  --total-batches 10 \
  --batch-interval 1

# with optional args
osc-cli osc-load-test-udp \
  --remote-ip-address 10.10.209.5 \
  --remote-port 8000 \
  --messages-per-batch 100 \
  --total-batches 10 \
  --batch-interval 1 \
  --message-rate 50

osc-cli osc-load-test-udp \
  --local-ip-address 0.0.0.0 \
  --local-port 51000 \
  --remote-ip-address 10.10.209.5 \
  --remote-port 8000 \
  --messages-per-batch 100 \
  --message-rate 50 \
  --total-batches 10 \
  --batch-interval 1 \
  --custom-address /my/custom/address

TCP Load Test:

# minimal required args
osc-cli osc-load-test-tcp \
  --remote-ip-address 127.0.0.1 \
  --remote-port 8001 \
  --messages-per-batch 100 \
  --total-batches 10 \
  --batch-interval 1

# with optional args
osc-cli osc-load-test-tcp \
  --remote-ip-address 10.10.209.5 \
  --remote-port 8001 \
  --messages-per-batch 100 \
  --total-batches 10 \
  --batch-interval 1 \
  --message-rate 50

# with all args
osc-cli osc-load-test-tcp \
  --local-ip-address 0.0.0.0 \
  --local-port 51000 \
  --remote-ip-address 10.10.209.5 \
  --remote-port 8001 \
  --messages-per-batch 100 \
  --message-rate 50 \
  --total-batches 10 \
  --batch-interval 1 \
  --custom-address /my/custom/address

Integration Testing

Integration testing commands send messages to a remote application and validate the responses. The remote application should echo back OSC messages to the local listener port.

Args

| Flag | Option | Type | Required | Description | Example | Default | |------|--------|------|----------|-------------|---------|---------| | -i | --remote-ip-address <ip> | string | Yes | Remote IP to send messages to | 10.10.209.5 | | | -p | --remote-port <port> | number | Yes | Remote port to send messages to | 8000 | | | | --mode <mode> | string | Yes | Test mode: "single" or "load" | single | | | | --local-ip-address <ip> | string | No | Local IP to listen for responses | | 0.0.0.0 | | | --local-port <port> | number | No | Local port to listen for responses | | 57120 (UDP) / 57121 (TCP) | | -a | --address <address> | string | No | OSC address to send | /test | /test | | | --args <args...> | string[] | No | Arguments to send | hello 123 | | | | --expected-address <address> | string | No | Expected response address | /response | sent address | | | --expected-args <args...> | string[] | No | Expected response args | ok 1 | sent args | | | --timeout <ms> | number | No | Response timeout | | 5000 | | | --messages-per-batch <n> | number | No | Messages per batch (load mode) | | | | | --total-batches <n> | number | No | Total batches (load mode) | | | | | --batch-interval <seconds> | number | No | Interval between batches (load mode) | | | | | --message-rate <n> | number | No | Messages per second (load mode) | | |

UDP Integration Test (single message):

# Send a message and validate the response matches
osc-cli test-osc-udp \
  --mode single \
  -i 127.0.0.1 \
  -p 8000 \
  -a /test \
  --args hello 123

# With custom expected response
osc-cli test-osc-udp \
  --mode single \
  -i 127.0.0.1 \
  -p 8000 \
  -a /ping \
  --expected-address /pong \
  --expected-args ok

UDP Integration Test (load test):

# Load test with throughput validation
osc-cli test-osc-udp \
  --mode load \
  -i 127.0.0.1 \
  -p 8000 \
  --messages-per-batch 100 \
  --total-batches 10 \
  --batch-interval 1

TCP Integration Test (single message):

osc-cli test-osc-tcp \
  --mode single \
  -i 127.0.0.1 \
  -p 8001 \
  -a /test \
  --args hello 123

TCP Integration Test (load test):

osc-cli test-osc-tcp \
  --mode load \
  -i 127.0.0.1 \
  -p 8001 \
  --messages-per-batch 50 \
  --total-batches 5 \
  --batch-interval 2 \
  --message-rate 100

Exit codes:

• 0 - Test passed (single: response matched; load: no dropped messages)
• 1 - Test failed (timeout, mismatch, or dropped messages)

Development

Please get in there if you want. This repo uses eslint 8 for linting AND code style.

VSCode Example Settings

{
  "editor.formatOnSave": true,
  "eslint.codeActionsOnSave.rules": null,
  "eslint.validate": [
    "typescript"
  ],
  "[typescript]": {
    "editor.tabSize": 2,
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": "explicit"
    }
  },
  "eslint.format.enable": true,
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "editor.tabSize": 2,
  "javascript.updateImportsOnFileMove.enabled": "always",
  "editor.rulers": [100]
}

npm run build        
npm start listen-udp -- <args> 

Wants and Desires

• roll in nodemon
• add some way to send messages on an interval