npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ios-sim-recorder-agent

v0.2.0

Published

Local agent for the OnDemand iOS Simulator Recorder plugin — records an iOS Simulator on your Mac and returns a video link.

Readme

iOS Simulator Recorder — local agent

Records an iOS Simulator on your Mac from the OnDemand Playground, and hands back a playable video link.

Playground  →  broker.on-demand.io  →  this agent (your Mac)  →  xcrun simctl
                                              ↓
                        Cloudinary  ←  upload  →  URL back to the Playground

The agent dials out to the broker, so nothing needs to reach into your machine — no port forwarding, no tunnel, no exposed server.

Setup

npx ios-sim-recorder-agent

First run asks four questions and saves the answers to ~/.config/ios-sim-recorder/config.json (mode 0600). After that the same command just connects.

You need OnDemand MQTT credentials: app.on-demand.io → API Keys Management → IoT(MQTT) credentials → create mqtt password. Your username there is your companyId; the password is shown once.

Cloudinary is optional. Without it recordings still work — they stay on your Mac and stop returns the local path instead of a URL.

npx ios-sim-recorder-agent doctor   # check this Mac can do the job
npx ios-sim-recorder-agent setup    # re-enter credentials

Leave it running while you use the plugin. Ctrl-C stops it, and stops any recording in progress.

Requirements

macOS with Xcode and at least one iOS Simulator runtime, plus Node 20+. No idb, no baguette, no Apple Silicon requirement — this drives xcrun simctl directly and works on Intel Macs.

Using it

In the Playground, with the agent running:

Start recording the iPhone 16 Pro on iOS 18.2

…drive the simulator…

Stop recording

stop answers immediately and the video is processed in the background, so the agent then asks for the link — usually in the same breath. If it says the recording is still processing, ask again in a moment.

Long recordings

A four-minute session produces roughly 290 MiB, well over Cloudinary's 100 MiB limit. Recordings above 80 MiB are therefore compressed with avconvert (Preset1280x720, giving 588x1280) before upload. Measured at 6.6x on a 90 MiB capture, so a heavy 290 MiB four-minute recording lands around 44 MiB. avconvert ships with macOS, so there is nothing to install; if it is somehow missing the original is uploaded and the size limit reported honestly.

Smaller recordings are uploaded untouched, because Cloudinary compresses better and keeps full resolution — a 13.65 MiB capture came back as 0.65 MiB at 1206x2622. Compression costs resolution and only earns its place when a recording would otherwise be rejected.

doctor reports whether compression is available.

Updating the plugin after a change

The agent and the OnDemand plugin have to agree on the topic list. A code change alone does nothing until the schema in the Playground is updated.

  1. Playground → Plugins → iOS Simulator Recorder → edit
  2. MQTT schema tab → replace the whole thing with plugin-schema.json
  3. Save
  4. Restart the agent so it subscribes to any new topics

The current schema has three topics:

| topic | operation | | --- | --- | | /simulator/recording/start | startSimulatorRecording | | /simulator/recording/stop | stopSimulatorRecording | | /simulator/recording/status | getRecordingStatus |

Suggested conversation starters:

  • Start recording the simulator
  • Stop recording and send me the video

Testing it end to end

Start the agent and leave that terminal alone — typing in it kills the agent mid-test:

node --env-file=.env bin/cli.mjs

Check first that only one agent is running. Two agents subscribed to the same topics both answer every command, which makes the results unreadable:

pgrep -fl 'bin/cli.mjs'

Short recording

In the Playground:

Start recording

…do something in the simulator for ten seconds…

Stop recording

In the agent log you should see, in order:

← .../start    data has no device_name when you did not name one
→ .../response state: active, with a recording_id
← .../stop
→ .../response state: processing          ← under a second
← .../status
→ .../response state: ready, with a url   ← usually the first poll

Then open the URL. It should be an .mp4 that plays in the browser.

Long recording — the case this was built for

Start recording

…drive the simulator for four minutes…

Stop recording

stop still answers in about a second. Processing then takes a minute or two, so get_recording will report processing once or twice before returning the URL. That is expected — the agent log shows compressing NNN MiB then compressed to NN MiB, uploading.

If the model stops polling and tells you it is still processing, just ask:

Is my recording ready?

The work completes in the background either way; polling only affects when you see the link.

What to check afterwards

ls -la ~/Library/Application\ Support/RemoteSimulatorAgent/artifacts/

The original recording stays on disk. Only the compressed copy is deleted after a successful upload.

Can other people use this?

Yes. MQTT topics are scoped by companyId, which is also the MQTT username, so each person's agent only ever receives their own organisation's commands. Nothing in the agent is specific to one account — it all comes from config.

Each user needs their own MQTT credentials, their own Cloudinary account (or none), and their own running agent.

Environment variables

These override the saved config, which is handy in CI or for development:

| Variable | Purpose | | --- | --- | | ONDEMAND_COMPANY_ID | companyId, also the MQTT username | | ONDEMAND_MQTT_PASSWORD | from IoT(MQTT) credentials | | CLOUDINARY_CLOUD_NAME / CLOUDINARY_API_KEY / CLOUDINARY_API_SECRET | upload target | | SIM_DEVICE_NAME | default simulator, e.g. iPhone 16 Pro | | SIM_RUNTIME | default iOS version, breaks ties between same-named devices | | LISTEN_ON_ACTIONS | 1 to also listen on /actions |

Commands

For users

npx ios-sim-recorder-agent            # connect and wait for commands
npx ios-sim-recorder-agent doctor     # check this Mac can do the job
npx ios-sim-recorder-agent setup      # re-enter credentials
npx ios-sim-recorder-agent --help     # all options
npx ios-sim-recorder-agent@latest     # force the newest published version

Leave the first one running while you use the plugin. Ctrl-C stops it, and stops any recording in progress.

Working on the code

git clone <repo> && cd sim-recorder-plugin
npm install
cp .env.example .env                  # then fill in the credentials
npm test                              # no broker, credentials or simulator needed
node --env-file=.env bin/cli.mjs      # run the agent from this checkout
node --env-file=.env bin/cli.mjs doctor

Three device-selection checks only run when exactly one simulator is booted, so the assertion count varies with the state of the machine.

agent.mjs is a module, not an entry point — run bin/cli.mjs.

Poking at the simulator directly

node cli.mjs devices                  # list simulators, flags ambiguous names
node cli.mjs resolve "iPhone 16 Pro"  # see how a name resolves
node cli.mjs smoke "iPhone 16 Pro" --runtime "iOS 18.2" --seconds 10
node cli.mjs status                   # in-flight recordings

cli.mjs start and cli.mjs stop as separate commands will not find each other — active recordings live in memory, so both must happen in one process. Use smoke, or the agent, which is long-running.

Releasing

npm test                              # must be green
npm pack --dry-run                    # check what would ship
npm version patch                     # or minor / major
npm publish                           # prompts for 2FA

Then verify what a new user actually gets, from the registry rather than this checkout:

cd /tmp && npx ios-sim-recorder-agent@latest doctor

Useful while debugging

xcrun simctl list devices available          # what is installed
xcrun simctl list devices booted             # what is running
xcrun simctl boot "<udid>"                   # boot one by hand
xcrun simctl shutdown all                    # stop them all
pkill -f 'bin/cli.mjs'                       # stop every running agent
ls -la ~/Library/Application\ Support/RemoteSimulatorAgent/artifacts/
ffprobe -v error -show_entries format=duration,size \
  -show_entries stream=codec_name,profile <file.mp4>

Two agents subscribed to the same topics will both answer every command, which makes the results unreadable. Check with pgrep -fl 'bin/cli.mjs' before starting one.

| File | | | --- | --- | | bin/cli.mjs | Command line: run, setup, doctor | | config.mjs | Config file and interactive setup | | defaults.mjs | Cloudinary credentials shipped with the package | | agent.mjs | Broker connection, subscribe, dispatch, reply | | routes.mjs | Maps an MQTT envelope onto an action, builds the reply | | recorder.mjs | Start/stop via simctl. Watchdog, disk guard, sandbox | | upload.mjs | Cloudinary upload, signed or unsigned preset | | plugin-schema.json | The MQTT schema to paste into the OnDemand plugin | | PENDING.md | Known gaps and what to do about them | | probe-media-api.mjs | Evidence that OnDemand's Media API cannot host these files |

Recordings are written to ~/Library/Application Support/RemoteSimulatorAgent/artifacts/.

Things worth knowing

Recordings are capped at 100 MB, which in practice bites long before the 15-minute ceiling. Measured rates: static screen ~50 KB/s, light use ~390 KB/s, heavy app switching ~700 KB/s, and one real session hit 1 MB/s — 118 MB in 100 seconds. Past the cap stop returns ARTIFACT_TOO_LARGE and the recording stays safely on disk.

simctl records variable frame rate. It only writes a frame when the screen changes, so the file's own duration drifts against wall clock — 12 seconds of a motionless screen produced 0.07 s of video. The duration_ms in the reply is accurate wall clock; the container's number is not.

simctl writes QuickTime, not MP4. The upload asks Cloudinary for format: mp4, which remuxes on the way in — otherwise the URL is a .mov that Safari plays and Chrome often won't.

OnDemand's Media API is not file storage. It requires a plugins array naming a plugin that can process the upload, and rate-limits per minute. That is why uploads go to Cloudinary. probe-media-api.mjs reproduces it.

Port 1883 is plaintext. OnDemand documents no TLS port for the broker, so commands and the returned URL travel unencrypted.

A failed upload is not a failed recording. stop returns partially_succeeded with the local path and the error, rather than telling you the recording was lost when it is safe on disk.

An already-booted simulator wins. If you have one open, that is what gets recorded — the configured default only applies when nothing is running, and an explicitly named device_name overrides both. This avoids booting a second simulator you cannot see while the one you are using sits there.

Device names are ambiguous. iPhone 16 Pro exists once per installed iOS runtime. Without a runtime, start returns SIMULATOR_AMBIGUOUS listing the candidates instead of guessing. Asking for a device on a runtime it is not installed on gives NO_SIMULATOR_MATCH naming the runtimes it does exist on. doctor warns about the ambiguity up front.

Cold starts take ~50 seconds. If the simulator isn't booted the agent boots it first; measured at 47 s. Whether OnDemand's reply window tolerates that is untested — a 27 s start has succeeded.