Skip to content
Back to search

createwithoscar

MarketplaceWorks with Claude CodeGitHub

OSCAR is a tool to create beautiful graphic user interaces (GUIs) to send OSC messages and control interactive installations (Resolume arena, Touch Designer, Ableton, Processing, PD, UNITY, Unreal, etc). Let's create beautiful, responsive and touchable interfaces.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 16 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/trafalmejo/OSCAR with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/trafalmejo/OSCAR'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/trafalmejo--oscar/badge.svg)](/listings/trafalmejo--oscar)

HTML

<a href="/listings/trafalmejo--oscar"><img src="/api/listings/trafalmejo--oscar/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines
  1. {
  2. "name": "createwithoscar",
  3. "owner": { "name": "Daniel Castaño", "url": "https://www.createwithoscar.com" },
  4. "metadata": {
  5. "description": "OSCAR: control interfaces for phones and tablets that send OSC, MIDI and DMX to show software and lights.",
  6. "homepage": "https://www.createwithoscar.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "oscar",
  11. "source": "./skills/oscar",
  12. "description": "Design phone and tablet control interfaces for Resolume, TouchDesigner, QLab, DAWs and DMX lights with OSCAR, and read a running OSCAR through its MCP server. Never sends to a rig.",
  13. "category": "productivity",
  14. "keywords": ["osc", "midi", "dmx", "resolume", "touchdesigner", "qlab", "lighting"]
  15. }
  16. ]
  17. }
README.md · README · 1,160 lines
  1. ![](assets/css/headerColor.png)
  2. # OSCAR - Visit [our website](https://www.createwithoscar.com/)
  3. OSCAR is a free, open-source app that turns any phone or tablet into a control surface for show software, lights and gear: design buttons, faders and pads in the browser, open them by QR code with no app to install, and send OSC, MIDI and DMX. It works with Resolume, TouchDesigner, QLab, Ableton Live and anything else that speaks OSC or MIDI, drives lights over Art-Net, sACN or a USB DMX interface, and runs on Windows, macOS, Linux and Raspberry Pi. An AI assistant can draft an interface for you over MCP.
  4. Build a layout in the browser, drop in buttons and sliders, point each one at an IP, port and OSC address, then publish it and open it from a phone or tablet on the same network to drive your software, gear and lights.
  5. <a href="https://www.youtube.com/watch?v=JO6r7gUNlgo&list=PLScMjUz4HRHxxDL2OYcNCMCsD-srohkIW" target="_blank"><img src="http://img.youtube.com/vi/ZcW8zBWRLf0/0.jpg" alt="OSCAR tool to create GUIs to control interactive installations" width="1200" height="600" border="10"/></a>
  6. ## Download
  7. Get the installer for your machine from the
  8. [latest release](https://github.com/trafalmejo/OSCAR/releases/latest):
  9. | Your machine | File |
  10. | --- | --- |
  11. | **Windows** (most PCs) | `OSCAR-*-win-x64.exe` |
  12. | **Windows on ARM** (Snapdragon laptops) | `OSCAR-*-win-arm64.exe` |
  13. | **Mac** with Apple Silicon (M1 and later) | `OSCAR-*-mac-arm64.dmg` |
  14. | **Mac** with an Intel processor | `OSCAR-*-mac-x64.dmg` |
  15. | **Linux** (most distributions) | `OSCAR-*-linux-x86_64.AppImage` |
  16. | **Linux** (Debian, Ubuntu) | `OSCAR-*-linux-amd64.deb` |
  17. | **Raspberry Pi** and other ARM Linux (64-bit OS) | `OSCAR-*-linux-arm64.AppImage` or `OSCAR-*-linux-arm64.deb` |
  18. From OSCAR 2.1.2 the Mac app is signed and notarized by Apple, and opens like
  19. any other. The Windows installers aren't code signed yet, so Windows warns you
  20. the first time: click *More info* then *Run anyway*. The copy from the
  21. Microsoft Store is signed by Microsoft and shows no warning.
  22. The first time OSCAR is opened in a browser, the canvas shows the **Showcase** template, where every widget works, so there is something to try straight away. After that the canvas is whatever you left on it, including empty. It is a template like any other: open **File → Open project or template…** to get it back, or to start from another.
  23. ## Keep in touch
  24. [**Sign up to the OSCAR mailing list**](https://forms.gle/1pGiDJDh3jur8Tq68) to
  25. hear about new releases, features and tutorials.
  26. OSCAR is a free and open source project, and it is better for every bit of
  27. feedback it gets. If you build something with it, we would love to know.
  28. ## Running from source
  29. Requires [Node.js 18 or newer](https://nodejs.org/en/).
  30. ```bash
  31. git clone https://github.com/trafalmejo/OSCAR
  32. cd OSCAR
  33. npm install # also installs the browser libraries under public/
  34. npm start # builds the bundle and starts the server
  35. ```
  36. OSCAR opens your browser at `http://localhost:8080` and also prints a LAN
  37. address such as `http://192.168.1.20:8080`. Open that second address on a phone
  38. or tablet on the same Wi-Fi to use the interface from there.
  39. Make sure your firewall allows communication between devices on the network.
  40. ### Useful commands
  41. | Command | What it does |
  42. | --- | --- |
  43. | `npm start` | Build the browser bundle, then run the server |
  44. | `npm run serve` | Run the server without rebuilding |
  45. | `npm run serve:at -- 18100` | Run the server on explicit ports (see below) |
  46. | `npm run dev` | Rebuild on change and restart on change |
  47. | `npm test` | Run the test suite |
  48. ### Running on explicit ports
  49. To run a second copy of OSCAR on one machine -- while developing next to a
  50. running show, say -- every port has to move, including the two source ports
  51. OSC is sent from. `serve:at` takes the HTTP port and derives the rest from it,
  52. so one number keeps a copy out of everyone else's way:
  53. ```bash
  54. npm run serve:at -- 18100 # http 18100, socket 18101, OSC in 18102, sources 18103/18104
  55. npm run serve:at -- 18100 18101 18102 # the same, with socket and OSC-in ports given explicitly
  56. ```
  57. It works the same in PowerShell, cmd and a Unix shell, and does not open a
  58. browser. A port given on the command line always wins, even over an
  59. `OSCAR_HTTP_PORT` left in your shell profile (you are told when that
  60. happens). A port you did not give is derived from the HTTP port unless the
  61. matching `OSCAR_*_PORT` variable is already set, in which case the variable
  62. wins. Two ports landing on the same number, or a value that is not a port,
  63. stop the start with both named. To set ports by hand instead, use the
  64. variables under [Configuration](#configuration):
  65. ```bash
  66. OSCAR_HTTP_PORT=8090 OSCAR_SOCKET_PORT=8091 OSCAR_LAN_PORT=5003 OSCAR_LOCAL_PORT=5004 npm run serve
  67. ```
  68. A variable set to something that is not a port stops the server with a
  69. message naming it, rather than falling back to the default and colliding with
  70. whatever you were trying to avoid.
  71. ### Building a desktop app
  72. OSCAR ships as an Electron app. `npm run electron` runs it from source, and
  73. the `dist` scripts produce installers under `release-builds/`:
  74. | Command | Output |
  75. | --- | --- |
  76. | `npm run electron` | Run the desktop app from source |
  77. | `npm run dist:win` | Windows installer (NSIS) |
  78. | `npm run dist:mac` | macOS disk image |
  79. | `npm run dist:linux` | Linux AppImage and .deb, for x64 and arm64 |
  80. Each platform's installer has to be built on that platform. All three are
  81. built for both Intel (`x64`) and ARM (`arm64`); on Linux the ARM build is what
  82. runs on a Raspberry Pi with a 64-bit OS. Electron no longer ships a 32-bit
  83. Windows build. Icons are generated from `build/icon.png`. The Microsoft
  84. Store package takes its logos from `build/appx/`, made from the same icon.
  85. ### Cutting a release
  86. Releases are built by GitHub Actions. Pushing a `v*` tag builds OSCAR on
  87. Windows, macOS and Linux in parallel and attaches all the installers to a
  88. **draft** GitHub release, which you then write notes for and publish:
  89. ```bash
  90. npm version 2.1.0 # bumps package.json and creates the tag
  91. git push --follow-tags # builds all three platforms, draft release appears
  92. ```
  93. To re-cut the current version in package.json, tag it directly:
  94. ```bash
  95. git tag v2.0.0 && git push origin v2.0.0
  96. ```
  97. Running the workflow by hand from the Actions tab builds the installers and
  98. leaves them as downloadable run artifacts without creating a release — useful
  99. for checking a build before tagging. A dry run signs with SignPath's test
  100. certificate. A tag signs only when the repository variable
  101. `SIGNPATH_RELEASE_READY` is `true`; it then waits for a maintainer to approve
  102. the two signing requests (the app, then the installers) in SignPath before the
  103. real certificate is used, so a release build pauses until that approval
  104. arrives. Until the variable is set, a tag builds unsigned Windows installers
  105. and does not pause.
  106. From OSCAR 2.1.2 the Mac app is signed with a Developer ID and notarized by
  107. Apple, so it opens without a warning. The Windows installers are not code
  108. signed yet: SignPath Foundation accepted OSCAR in October 2026 and the
  109. certificate is still pending, so Windows SmartScreen warns on first run (see
  110. the policy below for what happens once it arrives). Releases up to 2.1.0 are
  111. not signed on either system, and on macOS you right-click the app and choose
  112. Open.
  113. The Windows job also builds two packages for the Microsoft Store and leaves
  114. them as the run artifact `store-packages`. They are uploaded in Partner Center
  115. by hand; the Store signs them and updates its own copies, which is why OSCAR's
  116. update check is off when it runs from the Store (`main.js`). The package also
  117. declares its own firewall rules (`build/appxmanifest.xml`), so a Store copy
  118. never shows the Windows firewall prompt that the installer's copy does.
  119. ### Code signing policy
  120. Free code signing provided by [SignPath.io](https://about.signpath.io),
  121. certificate by [SignPath Foundation](https://signpath.org).
  122. Windows builds are signed inside the release workflow
  123. (`.github/workflows/release.yml`) once SignPath Foundation has issued the
  124. certificate: SignPath checks that the files came out of this repository's own
  125. GitHub Actions run, and a maintainer approves every release before the
  126. certificate is used. The artifact configurations that say which files may be
  127. signed, and at which version, are kept in `build/signpath/`. The first
  128. release signed this way will say so in its notes.
  129. The Mac app is signed in the same workflow with the maintainer's own Apple
  130. Developer ID certificate and notarized by Apple, under the hardened runtime
  131. with the entitlements in `build/entitlements.mac.plist`.
  132. Roles: committers and reviewers are the
  133. [contributors](https://github.com/trafalmejo/OSCAR/graphs/contributors);
  134. the approver is [Daniel Castaño](https://github.com/trafalmejo).
  135. Privacy: OSCAR does not transfer information to other networked systems
  136. unless you ask it to (sending OSC, MIDI or DMX, publishing an interface,
  137. signing in to OSCAR Pro), with two exceptions you can read in full in the
  138. source. Once a day it asks GitHub for the latest release number
  139. (`lib/updates.js`), and it sends anonymous usage counts to PostHog
  140. (`lib/telemetry.js`): no addresses, no project contents, no account, one
  141. random id, switched off in the About window or with `OSCAR_NO_TELEMETRY=1`.
  142. The privacy policy is at [createwithoscar.com/privacy](https://www.createwithoscar.com/privacy).
  143. When run as a desktop app, projects are stored in the per-user data folder
  144. (`%APPDATA%/OSCAR/projects` on Windows, `~/Library/Application Support/OSCAR/projects`
  145. on macOS) rather than next to the executable.
  146. ### Configuration
  147. All optional, set as environment variables:
  148. | Variable | Default | Purpose |
  149. | --- | --- | --- |
  150. | `OSCAR_HTTP_PORT` | `8080` | Web interface |
  151. | `OSCAR_SOCKET_PORT` | `8081` | Browser-to-server OSC bridge (browsers are told the port) |
  152. | `OSCAR_LAN_PORT` | `5001` | Source port for OSC sent to the network |
  153. | `OSCAR_LOCAL_PORT` | `5002` | Source port for OSC sent to this machine |
  154. | `OSCAR_OSC_IN_PORT` | `8880` | Where OSC coming back from the rig is received |
  155. | `OSCAR_DMX_PORT` | `0` (any free port) | Source port Art-Net and sACN are sent from; `6454` for a node that insists on it |
  156. | `OSCAR_DMX_HOLD_ON_EXIT` | unset | Set to `1` to leave DMX fixtures on their last look when OSCAR quits, instead of releasing them |
  157. | `OSCAR_PROJECTS_DIR` | `./projects` | Where saved projects are written |
  158. | `OSCAR_NO_OPEN` | unset | Set to `1` to not open a browser on start |
  159. | `OSCAR_NO_UPDATE_CHECK` | unset | Set to `1` to never check for new versions |
  160. ### Update checks
  161. Once a day at most, OSCAR asks GitHub whether a newer version has been
  162. released, and shows a dismissible notice in the editor if so. Nothing is
  163. downloaded or installed automatically, and you can skip a version or turn the
  164. check off entirely with `OSCAR_NO_UPDATE_CHECK=1`.
  165. This is the only request OSCAR makes to the internet. It sends nothing about
  166. you or your projects, times out quickly, and failing silently is the expected
  167. case on a venue network with no internet access.
  168. ## Widgets
  169. Drag these in from the **OSC** category, then set each one's IP, port and
  170. message in the settings panel (the gear icon).
  171. | Widget | Sends |
  172. | --- | --- |
  173. | **Button** | its Value ON when pressed, its Value OFF on release. As a toggle, it alternates. Leave Value OFF blank and it says nothing on release: software whose `/go` takes no argument must not hear it twice |
  174. | **Slider** | its value as it moves, with optional inverted range |
  175. | **XY Pad** | both values at once — `/pad 30 70` — or as `/pad/x` and `/pad/y` |
  176. On the XY pad, Y increases upward, and either axis can be inverted. Dragging
  177. sends at most one message per frame, and always sends the exact value where
  178. you let go.
  179. A slider can be **Vertical** from its Orientation setting. A size you have
  180. given a slider with the resize handles is kept when it turns: a wide, short
  181. box makes a squashed vertical control, so switch the orientation first and
  182. resize afterwards, or clear the width and height in the Style Manager.
  183. ### Following the rig (OSC in)
  184. OSCAR also receives. It listens for OSC on UDP port `8880`: point your
  185. software's OSC output at OSCAR's IP and that port. The port is fixed by
  186. design, as QLab's 53000 is, so a rig aimed at an OSCAR always finds it; the
  187. editor shows it in the top bar and as **Port in** under a widget's Data in,
  188. and only `OSCAR_OSC_IN_PORT` at startup moves it, for the rare machine where
  189. 8880 is taken. OSC runs both ways, so a
  190. widget's **OSC** section opens with a checkbox per direction: **Data in** and
  191. **Data out**. Tick **Data in** on a widget and it follows whatever arrives at
  192. its own Message address: a slider's
  193. thumb moves, an XY pad's handle jumps (`/pad 30 70`, or `/pad/x` and `/pad/y`
  194. in two-message mode), and a toggle button lights up and adopts the state, so
  195. the next press sends the opposite edge. A momentary button only lights up,
  196. because its state is your finger's.
  197. On a published interface OSCAR reads the message once and tells every device the
  198. result, the same way it tells them about a finger on a button. So every tablet
  199. shows the same thing, one that opens the interface later shows where the rig left
  200. it, and it works with no device looking at all. The media browser is the one
  201. exception: each page reads the message for itself.
  202. You do not have to type the address. Click **Learn** on the title of the
  203. widget's OSC section, then send a message from your software (move the thing you
  204. want the widget to follow). The widget takes the address of the first message
  205. that arrives and turns **Data in** on. Learn gives up after fifteen seconds, and a
  206. second click calls it off.
  207. Data in is off by default, so nothing starts moving on its own. Untick **Data
  208. out** and a widget keeps following the rig while sending nothing. **Master
  209. comms**, at the top of every widget, is over all of it: a widget with it off
  210. is deaf as well as silent on every protocol, so you can lay an interface out
  211. while the rig is live. A hand on a control outranks the network: while you
  212. are dragging a slider or a pad, or holding a button, what arrives is ignored
  213. until you let go. A widget never sends in answer to what it hears, so software
  214. that echoes its own state cannot start a loop with OSCAR. A value that cannot
  215. be read as a number is ignored, never treated as `0`. A button that sends no
  216. argument has nothing to follow: a bare address says nothing about its state.
  217. Incoming addresses may be OSC 1.0 patterns -- `/layer*/clip`, `/ch[1-3]`,
  218. `/{play,stop}` -- and reach every widget they match; a widget's own Message is
  219. always taken literally, and always reached by its own exact text, even one
  220. like `/layer[1]/opacity`. Software that answers to the port a message came
  221. from (OSCAR's source ports, `5001` and `5002`) is heard as well, so replies
  222. need no configuration. If the OSC-in port is busy or cannot be opened when
  223. OSCAR starts, it says so and carries on: sending is unaffected.
  224. ### Driving lights directly (DMX over Art-Net, sACN and USB)
  225. A button, slider or XY pad can drive lighting fixtures directly, with no
  226. lighting software in between. A widget's settings are grouped in collapsible
  227. sections, one per protocol. A section shows its **Data in** and **Data out**
  228. checkboxes and nothing more; the rest of its settings appear when a direction
  229. is switched on, and each setting belongs to its direction, so an Out port is
  230. not on screen when nothing goes out. DMX only runs one way, from the desk to the
  231. fixture, so its section has the one direction: open **DMX** and tick **Data
  232. out**. Leave OSC's **Data out** ticked to keep driving software at the same
  233. time, or untick it to drive the fixture alone. Each section's title carries a
  234. small light per direction, **IN** and **OUT**, green while that direction is
  235. live, so a collapsed section still says what it is doing. The DMX section
  236. holds:
  237. | Setting | Meaning |
  238. | --- | --- |
  239. | **Protocol** | Art-Net (UDP 6454), sACN / E1.31 (UDP 5568), or a USB interface on a serial port: **Enttec Pro** (also DMXKing and the many Pro-protocol clones) or **Open DMX** |
  240. | **Node or port** | On the network: the node's address; blank broadcasts on Art-Net and multicasts on sACN, which every node on that network hears. On USB: the serial port (`COM3`, `/dev/ttyUSB0`), a part of its name, or blank for the first interface found |
  241. | **Universe** | `0`-`32767` on Art-Net (the 15-bit Port-Address), `1`-`63999` on sACN, `1` on USB (an interface is one universe) |
  242. | **Channel** | The first channel of the widget's block, `1`-`512` |
  243. | **Channels** | How many channels from there |
  244. A slider sends its level (`0`-`255` across its own Min-Max range, so a slider
  245. labelled 20-2000 still means full at the top; Invert mirrors it). A button
  246. sends full while on and out while off, whatever its Value ON and OFF say for
  247. OSC. An XY pad puts X on the first channel and Y on the next: pan and tilt on
  248. a moving head. Values fill the block in order and the last one repeats, so a
  249. slider over three channels dims an RGB fixture as a whole. A block that would
  250. run past channel 512, or is too narrow for the widget's values, is refused in
  251. the panel and never sent. OSC's Data out is on and DMX's is off on every widget
  252. until you change them, so a project made before this existed behaves exactly
  253. as it did, and one saved while this was a single **Output** list opens with
  254. the matching boxes ticked.
  255. DMX is a stream, not a message: fixtures expect the frame to be repeated, and
  256. an sACN receiver drops a source that goes quiet for 2.5 seconds. So OSCAR
  257. keeps every universe it drives on the air until the widget driving it is
  258. deleted or switched back to OSC, or OSCAR quits, and then hands the channels
  259. back by sending them at zero (on sACN, with the stream-terminated packets the
  260. standard asks for). Several widgets on one universe are merged
  261. highest-takes-precedence where their blocks overlap, as a lighting desk
  262. would. A tablet disconnecting or a phone locking its screen releases nothing:
  263. whatever it last set stays up until something changes it. Quitting OSCAR
  264. releases everything unless `OSCAR_DMX_HOLD_ON_EXIT=1`, for a permanent
  265. installation that should hold its look through a restart. As with OSC, a
  266. value that cannot be read is dropped rather than sent as `0`: a dropped value
  267. must never black a rig out.
  268. A **USB interface** needs no network at all. An Enttec DMX USB Pro, a DMXKing
  269. ultraDMX or one of the many interfaces that speak the Pro protocol makes the
  270. DMX signal itself, so it is as dependable as a network node: OSCAR hands it
  271. the frame on every change and on the keepalive, and it repeats it on its own.
  272. An Enttec Open DMX USB or its clones is a bare serial chip, and this computer
  273. has to make the signal, forty frames a second, for as long as the universe is
  274. driven; that works, and a busy computer can show it as a flicker on the rig.
  275. Both use the serial driver OSCAR ships for boards. The port is opened when the
  276. first frame goes to it and held; an interface that is not there yet is
  277. reported once and looked for again every two seconds, so plugging it in later
  278. is enough.
  279. Packets leave from any free port (`OSCAR_DMX_PORT`), so OSCAR can run next to
  280. lighting software that itself receives Art-Net on 6454. If the port you pin
  281. cannot be opened, OSCAR says so at startup and everything else still works.
  282. On a computer with more than one network connection -- Wi-Fi for the internet
  283. and a cable to the lighting switch, say, or a virtual machine's adapter -- a
  284. blank node is not enough: the operating system puts a broadcast on one
  285. connection only, usually the one with internet on it, and the node on the
  286. other never hears it. Name the node's address, or the lighting network's own
  287. broadcast address (`2.255.255.255` or `10.255.255.255` for the ranges Art-Net
  288. nodes ship on), and the packets go the right way.
  289. ## Running a show
  290. The editor lives at `/`. The preview lives at `/preview` — the same layout
  291. with every editing tool stripped out, as a phone or tablet shows it.
  292. Choose **File → Push to preview** to send the current layout to it.
  293. Every device showing `/preview` picks the new layout up straight away; there is
  294. no need to walk over and reload them.
  295. ### Sending MIDI
  296. Every widget that can drive DMX can send MIDI: open the **MIDI** section of its
  297. settings and tick **Data out**. It is a third protocol beside OSC and DMX, and
  298. any of the three can be on at once.
  299. | Setting | |
  300. | --- | --- |
  301. | **Data in**, **Data out** | A checkbox per direction, as for OSC. Both off on a new widget. |
  302. | **In port** | The MIDI port to listen on, from a list of the ports the computer running OSCAR has. Ticking Data in picks the first one, and Learn the one you touch. **First port** is whichever is first at the time. **All MIDI inputs** listens on every port, which on Windows takes them all from other programs. |
  303. | **Out port** | The MIDI port to send to, from the same kind of list. **First port** is whichever is first at the time. |
  304. | **Channel** | 1 to 16. Shared by both directions, as Type and Number are. |
  305. | **Type** | Control change, Note, Program change or Pitch bend. |
  306. | **Number** | The controller or note number, 0 to 127. |
  307. What a widget sends is its value scaled to MIDI's 0 to 127, the way DMX scales
  308. it to 0 to 255: a slider at the top of its range sends 127 whatever its Min and
  309. Max. A button sends note on at full velocity and note off, or 127 and 0 as a
  310. controller. A widget with several values uses the numbers that follow: a pad set
  311. to controller 20 sends X on 20 and Y on 21, a colour sends red, green and blue
  312. on three in a row. Program change sends a dropdown's value as it is when that is
  313. a whole number from 0 to 127, so options valued 0, 1, 2 pick programs 0, 1, 2.
  314. Pitch bend uses all 14 bits.
  315. The ports belong to the computer running OSCAR. A tablet or a phone showing a
  316. published interface sends MIDI through it, exactly as it sends OSC and DMX.
  317. To reach software on the same computer (Ableton Live, Resolume, a DAW) you need
  318. a virtual MIDI port. macOS has one built in: enable the **IAC Driver** in Audio
  319. MIDI Setup. On Windows install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)
  320. and create a port; OSCAR then lists it. On Linux, `snd-virmidi` or a JACK/ALSA
  321. bridge does the same.
  322. OSCAR opens a port the first time a widget sends to it and keeps it open. If the
  323. instrument is unplugged, it is looked for again every two seconds and picked up
  324. when it returns. Only notes, controllers, programs and bends are sent; system
  325. exclusive and clock are refused.
  326. #### MIDI in: a widget that follows a controller
  327. Tick **Data in** in the MIDI section and a knob, fader or pad on a MIDI
  328. controller moves the widget, on every page that shows it, the editor's canvas
  329. included. It is OSC's Data in over another wire, and keeps the same rule: **what
  330. comes in is never sent out**. The widget follows and says nothing, not in OSC,
  331. not in DMX, not in MIDI, so nothing can loop. A hand on the same widget sends as
  332. it always did.
  333. Click **Learn** on the title of the MIDI section and touch the control: the
  334. widget takes its port, channel, type and number. While Learn is waiting, what
  335. you play moves no other widget.
  336. - A fader, a number box: the level, across the widget's own Min to Max.
  337. - A button: held while a note is held; with a controller, on from halfway up. A
  338. button set to Toggle changes over on each press and ignores the release.
  339. - A dropdown: a program change picks the option with that value, or failing
  340. that the option at that position. Any other message picks along the list.
  341. - A pad: the Number is X and the next one up is Y. A colour: red, green and blue
  342. on three in a row. What is not touched stays where it was.
  343. OSCAR only opens the input ports that the widgets on an open page listen on, or
  344. every port if one of them asks for **All MIDI inputs**, and lets go of them when
  345. the last such page closes. On Windows a MIDI input belongs to whichever program opened it
  346. first, so a controller OSCAR is listening to is not available to other
  347. software, and the other way round; the console says when a port is in use.
  348. ### The bridge: sending on what comes in
  349. By rule, what comes in is only shown: an OSC message or a MIDI knob moves the
  350. widget on every screen, and nothing is sent on, which is what makes a loop
  351. with software that echoes its own state impossible. Each protocol's **Send
  352. when** setting relaxes that per widget: *Changed by the user* is the rule
  353. above and the default; *Changed by the user or by data in* also sends what
  354. Data in put the widget in. That makes OSCAR a bridge -- a MIDI fader box
  355. drives Resolume through an interface, a sensor's OSC drives a fixture -- and any
  356. of MIDI in or OSC in can feed any of OSC, MIDI or DMX out.
  357. The bridged send happens **once**, from whoever serves the interface: the
  358. server for published interfaces, however many devices show them and whether any
  359. browser is open at all; a downloaded file for itself, which is why such a
  360. file should be open in one copy only. The editor's canvas and the preview
  361. only follow, so a project open in the editor while it is published never
  362. drives the rig twice. Two things stand between a bridge and a loop: the
  363. **Loop guard** (default on) passes on only a change that changed the value,
  364. so an echo moves nothing and nothing is re-sent -- untick it for triggers
  365. where a repeat is the event, and never point such a widget back at its own
  366. source -- and under the guard, no widget bridges more than 200 sends a
  367. second. The editor asks for confirmation when Data in and a bridged Send
  368. when first meet on one widget.
  369. `MIDI` in `lib/features.js` hides the section if it has to be taken out of a
  370. release. About (Report a problem) says how many ports OSCAR can see, which is
  371. the first thing to check when nothing arrives or nothing is heard.
  372. ### Locking an installation
  373. By default anyone on the network can open the editor at `/` and change things.
  374. For an installation or a show, press the padlock in the toolbar.
  375. While OSCAR is locked:
  376. - Other devices can still open `/preview` and use the controls
  377. - Visiting `/` from another device sends them to `/preview` instead
  378. - Saving, loading and deleting projects are refused
  379. - Only the computer running OSCAR can edit, or unlock it again
  380. Physical access to that computer is what grants editing, so there is no
  381. password to leak over a venue's network or forget before doors open. The
  382. setting is remembered, so a machine that reboots overnight comes back locked.
  383. `OSCAR_LOCKED=1` starts it locked.
  384. This stops editing, not sending: the OSC bridge stays open, because that is how
  385. the tablets work at all. Anyone who can reach OSCAR can still send OSC to your
  386. rig. If that matters, the answer is a separate network for the control devices,
  387. not a setting in OSCAR.
  388. ## Saving your work
  389. There is no Save to press. A project lives in OSCAR, on the computer OSCAR
  390. runs on, and every change is saved a moment after you make it. The top bar
  391. shows the project's title, and beside it how it stands: **Saving**, **Saved**,
  392. or **Not saved** when OSCAR cannot be reached. What has not been confirmed
  393. stays in your browser and is sent as soon as OSCAR answers, even after the
  394. tab was closed in between.
  395. - **The title** is in the top bar: click it to rename. The same title names
  396. the published interface, the phone's tab and, with OSCAR Pro, the portal.
  397. A published interface's address does not change when you rename.
  398. - **File → New project** starts an empty canvas called "Untitled". It joins
  399. your projects at its first change, so one you only looked at leaves nothing
  400. behind. A template opens the same way, named after the template.
  401. - **File → Open project or template…** lists your projects and the templates.
  402. - **File → Make a copy** makes a second project like this one.
  403. - **File → Export a copy…** writes an `.oscar` file wherever you choose: a
  404. backup, or something to send. **File → Open a file…**, or double-clicking
  405. an `.oscar` file, brings one in as a project. If that project is already in
  406. OSCAR, you are asked whether to replace it or keep both.
  407. - **File → Revert to…** is the way back, since there is no closing without
  408. saving: to how the project was when this window opened it, or to the
  409. version that is published.
  410. - **The same project open in two windows:** the one that saves second is told
  411. the project changed somewhere else, and chooses which version to keep.
  412. Changes are not merged.
  413. Projects are plain JSON files in the `projects/` folder next to OSCAR, so
  414. they can still be copied and backed up by hand. Because they are on the
  415. computer OSCAR runs on, any browser that may edit sees the same projects.
  416. > **Note for OSCAR 1.x users:** the old online accounts at
  417. > `account.createwithoscar.com` no longer exist. OSCAR now stores everything on
  418. > your own machine, and no longer asks you to log in.
  419. ### Templates and widget styles
  420. **File → Open project or template…** also lists the templates OSCAR ships
  421. with: whole interfaces to start from, every control on them working. Some are built for one piece of software
  422. and carry a card listing its addresses: the **Resolume Video Desk** (a clip
  423. grid, layer strips, crossfader, master, tempo; Resolume's own addresses, port
  424. 7000) and the **QLab Stage Manager's Desk** (GO, STOP, PANIC, playhead and a
  425. cue sheet; QLab's own addresses, port 53000, every key a bare address sent
  426. once) and the **TouchDesigner Parameter Rack** (parameters out, an audio level and a sensor back in, with the two-CHOP recipe on its card; an OSC In CHOP listens on port 10000; next to it in `public/templates/` is `touchdesigner-parameter-rack.py`, a script that builds the whole demo network inside TouchDesigner in one go, so the picture moves and the two meters read something; two sketches that use every control on the rack, caption included, are on the website as ready `.tox` files, each with its `.py` script at the same address: [Type Tunnel](https://www.createwithoscar.com/touchdesigner/oscar-type-tunnel.tox) (the caption flies through a tunnel, tiles into a wall, or orbits) and [Kaleido Feedback](https://www.createwithoscar.com/touchdesigner/oscar-kaleido-feedback.tox) (a kaleidoscope of 3, 6 or 12 mirrors), whose sensor meter reads the picture itself, so no hardware is needed; the template wears the Sci-fi HUD style rather than a look of its own). The **DMX Console, 12 Channels** is a
  427. lighting desk whose controls send DMX. **Big Thumb** puts one control on each screen of a phone, the size of a
  428. hand. The rest are objects to play with: a boombox, a walkie-talkie, an arcade
  429. cabinet, a cassette player, a CD player, a click-wheel player, a turntable and
  430. a TV remote. A template that is built for one program has been written from
  431. that program's documentation; if you have it, try it and tell us what moved.
  432. The **widget style** picker in the top bar dresses every control at once:
  433. Default, Amber Minimal, Cyberpunk, Supabase, Tangerine, **Neon** (every
  434. control a lit tube, with the flicker of one striking) and **Sci-fi HUD**
  435. (corner brackets, a segmented meter, a crosshair on the pad), each light or
  436. dark. A template that brings its own look is listed as *Page's own*; pick a
  437. style and it is redrawn in that style's colours.
  438. ## How it works
  439. ```
  440. Browser (grapesjs editor + OSCAR widgets)
  441. | socket.io :8081
  442. v
  443. OSCAR server (Node/Express)
  444. | UDP
  445. v
  446. Your lighting / video / sound software
  447. ```
  448. Widgets carry their own OSC settings (IP, port, address, value). When you press
  449. a button or move a slider the browser sends that over socket.io to the OSCAR
  450. server, which emits the actual OSC packet over UDP.
  451. ## OSCAR for AI assistants (MCP)
  452. A running OSCAR is an MCP server, so an assistant such as Claude can read it
  453. and build for it: your projects, what is published and what each widget is
  454. set to, the MIDI ports, the recent network activity ("why isn't my light
  455. responding?"), every widget's settings and how an interface is written -- and
  456. it can draft a whole interface as HTML, judged by the widgets' own validators
  457. and listed under **File → Open project or template…** with a Draft badge for you to review. **No
  458. tool touches the wire**: nothing is sent, published or driven, and no project
  459. is changed; a draft does nothing until you open it and decide.
  460. Connect an assistant once, with OSCAR running and the **MCP** pill in its top
  461. bar green:
  462. ```
  463. claude mcp add oscar -- npx -y createwithoscar
  464. ```
  465. That is Claude Code. Claude Desktop takes the one-click bundle `OSCAR.mcpb`
  466. from the website; any other MCP app takes a server with the command `npx` and
  467. the arguments `-y createwithoscar`.
  468. The same repository is also a **skill**, a **Claude Code plugin** and a
  469. **Gemini CLI extension**, all from [`skills/oscar/`](skills/oscar/): how to
  470. design a good phone or tablet surface, what Resolume, TouchDesigner, QLab,
  471. DAWs and DMX expect on the wire, and every widget with its settings
  472. (`references/widgets.md`, generated from the registry by `npm run build:skill`).
  473. A skill works in any assistant that reads them, with or without OSCAR running:
  474. ```
  475. npx skills add trafalmejo/OSCAR # the skill alone, any assistant
  476. claude plugin marketplace add trafalmejo/OSCAR # Claude Code: the skill plus the MCP server
  477. claude plugin install oscar@createwithoscar
  478. gemini extensions install https://github.com/trafalmejo/OSCAR
  479. ```
  480. `test/skill.test.js` keeps the three in step with the app and with the
  481. helper's published version. [`createwithoscar`](createwithoscar/) is
  482. the helper the assistant starts: a small program with no dependencies that
  483. finds this OSCAR through `~/.oscar/mcp.json` (written on every start) and
  484. passes each request on. When OSCAR is not running the assistant still sees
  485. the tools, and is told to ask you to start it.
  486. The tools: `status`, `list_projects`, `read_project`, `list_published`,
  487. `read_published`, `installation_map`, `midi_ports`, `recent_activity`,
  488. `describe_widgets`, `validate_draft` and `create_draft`, the only one that
  489. writes anything. `installation_map` is the whole installation in one answer:
  490. everything the published interfaces talk to and listen for (each OSC
  491. destination, MIDI port and DMX output, with the controls behind it), what
  492. this computer has plugged in, and what does not add up. It is worked out
  493. from settings and sends nothing onto the network.
  494. OSCAR's own endpoint is `http://127.0.0.1:<port>/mcp`, with the token from
  495. that same file as a bearer token. It answers this machine only, the token is
  496. new on every start, the switch behind the MCP pill closes it, and `MCP: false` in
  497. `lib/features.js` removes the whole thing.
  498. Working on the helper: it lives in `createwithoscar/` and is published to npm
  499. from there (`npm publish`, by its owner). `npm run build:mcp` rewrites the
  500. copy of the tools it carries and the bundle's manifest after
  501. `lib/mcp/tools.js` changes (a test fails until it is run), and
  502. `npm run pack:mcpb` packs `release-builds/OSCAR.mcpb`. From a source checkout,
  503. `node scripts/oscar-mcp.js` is the same program.
  504. ## Tutorials
  505. 1. Youtube Channel [OSCAR](https://www.youtube.com/channel/UCyIxOoajn_4Nj8Mjz2k-3qA)
  506. ## Contributing
  507. Bug reports and pull requests are welcome on the
  508. [issue tracker](https://github.com/trafalmejo/OSCAR/issues), and you can
  509. [sign up for OSCAR news](https://forms.gle/1pGiDJDh3jur8Tq68) to follow along
  510. with what is coming next.
  511. ## License
  512. BSD 3-clause
  513. ## Meter (level display)
  514. A **Meter** shows a level instead of sending one: an audio level, a fixture's
  515. intensity, a playhead, whatever the rig reports at the address in its Message
  516. setting. It sends nothing, so it has no IP or port, and Data in is on from the
  517. start. Min and Max are the scale, the bar is horizontal or vertical from its
  518. Orientation setting, and Value is where it sits until the first reading
  519. arrives, so you can see the layout before anything is feeding it.
  520. A level can also come from a MIDI controller: the meter's **MIDI** section has
  521. Data in, the port, channel, type and number, and **Learn**, and no Data out.
  522. The controller's 0 to 127 is laid across Min to Max.
  523. **Peak hold** keeps a marker at the highest recent reading for that many
  524. seconds (`0` turns it off). A reading at or above the marker moves it up at
  525. once; when the hold has passed the marker falls back onto the bar on its own,
  526. whether or not anything new has arrived, so it works with software that only
  527. sends a value when it changes. It falls to the last reading, never to zero: a
  528. meter fed nothing keeps showing its last reading.
  529. A meter never drops to zero on its own. A value that cannot be read as a
  530. number holds the last reading, because an empty bar reports silence on a
  531. channel that may be at full, and a meter with **Master comms** off freezes where
  532. it is rather than emptying.
  533. ## Colour picker
  534. The **Colour** widget is the tablet's own colour picker: tap the swatch and
  535. the operating system's picker opens. Dragging inside it sends at most one
  536. message per frame, and closing it sends the exact colour chosen. **Send as**
  537. chooses the shape on the wire and **Range** the scale, because software
  538. disagrees on both:
  539. | Send as | On the wire |
  540. | --- | --- |
  541. | **3 values (r, g, b)** | `/colour 1.0 0.533 0.0` |
  542. | **4 values (r, g, b, a)** | the same with the **Alpha** setting appended |
  543. | **hex string (#rrggbb)** | `/colour "#ff8800"` |
  544. **Range** is `0 to 1` for software that reads a colour parameter as floats
  545. (Resolume) or `0 to 255` for software that reads pixel values (TouchDesigner
  546. and most pixel-minded tools). Alpha is a setting rather than part of the
  547. picker, because no native picker has an alpha channel; it is always typed as
  548. `0`-`1`, whatever Range says, and a blank or unreadable Alpha stops the
  549. message rather than going out as `0`, which is fully transparent. The
  550. **Colour** setting is the swatch's value as a hex code, so a colour can be
  551. typed as well as picked; `#f80` and `f80` both mean `#ff8800`.
  552. With DMX's **Data out** ticked, red, green and blue land on three consecutive
  553. channels, whatever Send as and Range say, so the block is three channels
  554. wide by default and drives an RGB fixture as it stands; over a wider block
  555. the blue repeats, and a narrower one is refused. Alpha never reaches the
  556. fixture. With **Data in** on, a colour arriving at Message fills the swatch
  557. in either shape OSCAR sends -- the hex string, or three channels on the
  558. configured Range, with a fourth ignored. Channels may arrive as numbers or
  559. as numbers spelled as text; three readable numbers are always channels, even
  560. when the first (`"255"`, `"000"`) would also pass for a short hex code. A
  561. colour that cannot be read leaves the swatch as it was: the native control
  562. turns anything it does not understand into black, and a rig sending nonsense
  563. must not black a colour out.
  564. While a colour is being dragged inside the picker the rig is not heard, so
  565. the swatch is not snatched from under the hand. That holds on pickers that
  566. report the colour as it moves (macOS, iOS). A picker that reports only when
  567. it is closed (the Windows dialog, Android) gives the page no sign that it is
  568. open, so a colour arriving meanwhile repaints the swatch behind it; pressing
  569. OK still sends the colour that was picked.
  570. **Argument type** int needs **Range** `0 to 255`. Whole numbers on `0 to 1`
  571. would round every channel to 0 or 1 -- eight colours in all, and a middling
  572. Alpha going out as 0 -- so the panel refuses the combination.
  573. ## Typing a value (text, number and dropdown widgets)
  574. Three widgets take a value directly instead of from a gesture, for the cues
  575. you already know: a clip name, cue 12, exactly 127.
  576. | Widget | Sends |
  577. | --- | --- |
  578. | **Text Input** | whatever you type, as a string by default, or as any other argument type |
  579. | **Number Input** | the number you type, as a float or an int, with optional **Min**, **Max** and **Step** |
  580. | **Dropdown** | the value of the option you pick |
  581. The text and number boxes send when you press **Enter** or leave the box,
  582. never while you type: `12.5` would otherwise go out as `1`, then `12`, then
  583. `12.5`, and the first two are real cues a rig will act on. Enter sends even
  584. when the value has not changed, because re-sending a cue on purpose is a
  585. normal thing to do. A click on the number box's stepper arrows is one
  586. finished value and goes out at once. An empty or half-typed box sends
  587. nothing, and neither does a number outside Min-Max or off the Step: the box
  588. keeps what you typed and shows a red edge, rather than the rig going to a
  589. value nobody typed.
  590. A dropdown's options are typed on one line in its **Options** setting, as
  591. `Label=value` pairs separated by commas or semicolons -- `Red=1, Green=2,
  592. Blue=3` -- or bare values, `1, 2, 3`, which are their own labels. The list is
  593. built from that setting every time the widget is drawn and is never stored
  594. in the markup, so it cannot drift from what the panel says.
  595. The panel refuses a value the chosen **Argument type** cannot carry -- `abc`
  596. as a float -- and checks the other way round too: switching a box that holds
  597. `GO` to float, or a dropdown whose options say `Red, Green` to int, is
  598. refused rather than leaving a widget that looks live and sends nothing.
  599. The number box and the dropdown can drive DMX like the slider (tick **Data out** in its **DMX** section).
  600. The number is the level: `0`-`255` as typed, or, when Min and Max are both
  601. set, scaled within them, so a box that takes `0`-`100` puts `50` at half. A
  602. dropdown of `Off=0, Half=128, Full=255` is a three-step dimmer. All three
  603. follow the rig with **Data in** on: a value arriving at Message fills the box
  604. or selects the option that sends it, and goes no further. A box you are in
  605. the middle of typing into is left alone until you commit or leave it, and a
  606. value no option sends leaves the dropdown where it was.
  607. A typed DMX level is refused, not pinned, when it is out of range: without
  608. both Min and Max the box's limits are `0`-`255`, so a slipped `-1` is not a
  609. blackout and `300` is not full. While DMX's **Data out** is ticked the panel
  610. likewise refuses a dropdown option that is not a number from `0` to `255`.
  611. The settings are checked against each other: a Min, Max, Step, DMX Data out or
  612. Argument type that the current Value could not be sent under is refused until
  613. the Value is changed, and a value arriving from the rig is brought inside the
  614. limits and onto the Step, so Enter on what the box shows always sends.
  615. An empty text box sends nothing under any argument type, and the Enter that
  616. confirms an IME composition is not a send. Two dropdown options may not send
  617. the same value -- the value is all that is stored, so the second could never
  618. be shown again -- and a label may contain `=`: the value is what follows the
  619. last one. Walking a dropdown with the arrow keys sends only the row you stop
  620. on, when you press Enter or leave the list; a click or a tap sends at once.
  621. ## Several devices on one interface
  622. Every device showing the same layout shows the same state. Toggle a button
  623. on one tablet and it lights up on the others, so the next press anywhere
  624. sends the opposite edge rather than the one that has already gone out; move a
  625. slider or an XY pad and the thumb or handle moves on every other device. A
  626. tablet that connects mid-show is caught up the moment it loads the interface,
  627. and a widget following the rig with **Data in** on passes what it hears along
  628. too, so a device joining later starts where the rig left things. Nothing
  629. needs switching on: two tablets agreeing is not a setting.
  630. Only what a widget shows travels -- on or off, a value, a position -- keyed
  631. by the widget's id in the project, over the same socket the OSC bridge uses.
  632. The device that acted is the only one that sends OSC or DMX: the others
  633. redraw and stay silent, and a device is never told what it just said itself,
  634. nor anything that did not actually change, so two tablets cannot trade the
  635. same value back and forth. A hand outranks the network here as it does with
  636. OSC in: while you are dragging a slider or a pad, or holding a button, what
  637. the other devices report is ignored until you let go. Pushing a new layout
  638. to the preview forgets every state, because the widgets in the old one may
  639. not exist in the new.
  640. The devices are the pages showing the interface (`/preview`). The editor is
  641. not one of them: it neither follows the tablets nor moves them, so a show
  642. running on the tablets never rewrites the values saved in the project you
  643. have open, and a different project open in the editor cannot reach them.
  644. What the rig sends is recorded for whoever joins later but not passed
  645. between the tablets, since each of them heard it already. A slider catches
  646. up when you lift your finger with whatever another device did while you were
  647. resting on it; a momentary button held on a tablet that drops off the
  648. network is let go on the others; and if the server restarts, the tablets
  649. tell it again what they show when they reconnect.
  650. ## Media browser (pick a clip by its picture)
  651. A grid of thumbnails for choosing what plays: one tap on a tile sends that
  652. tile's value to **Message**, which is how Resolume, Millumin, QLab and most
  653. clip launchers select a clip -- by index or by name.
  654. The tiles are typed on one line in the **Items** setting, separated by
  655. semicolons, each as `label`, `label|value` or `label|value|image`:
  656. ```
  657. Forest; Waves; Stars sends 1, 2, 3 -- the tile's position
  658. Forest|7; Waves|12 sends 7, 12
  659. Forest|forest_loop|thumbs/forest.jpg sends "forest_loop" (Argument type: string)
  660. ```
  661. A tile with no value sends its position, counted from 1. **Argument type**
  662. is int, float or string. The image is a path next to OSCAR's pages (anything
  663. under `public/`, for example `assets/thumbs/forest.jpg`), an `http(s)://`
  664. address, or a `data:image/...` URL; anything else -- `javascript:`,
  665. `data:text/html` -- is refused by the panel and never reaches the page. A
  666. picture that fails to load is replaced by the tile's label. **Columns** sets
  667. how many tiles go in a row, and **Show labels** can be switched off for a wall
  668. of pictures (a tile with no picture always keeps its label). Give the widget
  669. a height and the grid scrolls inside it.
  670. A tile is picked when the tap ends on it, not when the finger lands, so
  671. scrolling the grid never launches the clip you happened to touch. Tapping the
  672. tile that is already selected sends again, because relaunching a clip is a
  673. real instruction. With **Data in** on, a value arriving at Message moves the
  674. highlight to the tile that sends it and nothing goes back out; a value no
  675. tile sends, or one OSCAR cannot read, changes nothing. Several tablets on one
  676. interface agree on the highlight without Data in. The highlight is never saved
  677. in the project: what is playing is the software's to say.
  678. The labels and URLs you type are put on the page as text, never as markup,
  679. and the tiles are rebuilt from Items every time the widget is drawn; they are
  680. not stored in the project and cannot be dragged out of the widget in the
  681. editor.
  682. This is a chooser, not a media library. It does not upload files, there is
  683. no asset picker (you type the path or URL), and it shows still images only --
  684. no video or animated previews, and it does not fetch thumbnails from
  685. Resolume or any other software.
  686. ## The phone itself: Motion and Feedback cue
  687. Two widgets are about the phone an interface is opened on rather than
  688. about the rig. Both are laid out and addressed like any other widget; what
  689. they do depends on what is holding them.
  690. **Motion** sends the phone's sensors, each reading as its own stream on
  691. its own address under the widget's Message, at the rate you set (the latest
  692. reading wins, so a sensor firing sixty times a second is twenty messages at
  693. a rate of 20). Tick the readings you want: orientation (alpha, beta, gamma,
  694. in degrees), acceleration (x, y, z in m/s², gravity taken out), acceleration
  695. with gravity (a steady tilt), rotation rate (degrees a second), and compass
  696. heading (one value, degrees from north). With Message `/phone`, orientation
  697. goes out as `/phone/orientation`, heading as `/phone/heading`, and so on.
  698. The box lists every stream it sends with the live values and the address
  699. beside each, so a glance at the phone says what is going where. Pages
  700. published before readings could be ticked separately keep their one Source
  701. on the plain Message. Nothing is shared between devices: a reading is one
  702. phone's own, and two phones on one surface are two streams. It works in
  703. the OSCAR app only: a phone's browser could give some of it, but not the
  704. same on Android and iPhone, and OSCAR offers a widget in the browser only
  705. when both get it. So it is not in the editor's palette (the `APP_WIDGETS`
  706. switch in lib/features.js puts it back, with an "App" badge): the way to
  707. the sensors is the OSCAR app itself, Settings → Send device sensors, which
  708. makes a page with this widget alone and sends every reading under
  709. `/device`. A page that already carries one keeps working; in a browser, as
  710. in the editor, its box says "needs the OSCAR app". In the editor and on a laptop the box says "open on a
  711. phone". On an iPhone the sensors are handed over only after a tap, so the
  712. box is a button that asks until then; Android asks nothing.
  713. **Feedback cue** is a light on the page. It listens on an address and, when
  714. a message arrives, lights up in its colour for the time you set and buzzes
  715. the phone, each one a checkbox. It is not a button: nothing happens when it
  716. is pressed. Its tooltip says what it is waiting for ("On /cue: light,
  717. vibrate"). A value above zero (or a bare message) is go; zero does nothing.
  718. Every message counts: two `/cue 1` are two cues, though a cue that lands
  719. while the phone is still buzzing from the last one rides on it. The light
  720. works everywhere, the editor included. Vibrate is Android only in a
  721. browser: an iPhone's Safari cannot, and on one the face says "needs the
  722. app for vibration" while the light still lights. The OSCAR app vibrates on
  723. both platforms, as media does on Android, so it plays even with touch
  724. feedback switched off.
  725. Through OSCAR Pro's public links, OSCAR hears for the phone and passes the
  726. state on, so feedback reaches a phone on mobile data too.
  727. The rule behind both: a page OSCAR serves on the LAN is plain `http`, not a
  728. secure context, and browsers hold sensors, vibration and the wake lock back
  729. from one, each differently. Motion follows the rule that OSCAR offers in a
  730. browser only what every phone's browser gives, so it is the OSCAR app's;
  731. Vibrate is offered with its limit named (Android only). The app runs the
  732. same page in a secure context with the phone's own hardware behind it.
  733. ## Arduino and other boards
  734. **A board with Wi-Fi or Ethernet already works, and always has.** OSCAR
  735. sends OSC over UDP to whatever IP and port a widget names, and an ESP32 on
  736. your network is one more thing with an IP and a port, exactly like Resolume.
  737. There is nothing to switch on: flash `tools/arduino/oscar_wifi`, read the
  738. address it prints, and type it into the widget's **Ip** and **Port**.
  739. **A board on a USB cable** (Uno, Nano, Mega, Leonardo, Pico) has no address,
  740. so OSCAR opens the serial port for you.
  741. > Still to be tried on real boards before 2.1 ships; the to-do list has it.
  742. > A board with Wi-Fi or Ethernet, above, is not affected.
  743. 1. Flash `tools/arduino/oscar_serial` (115200 baud, no libraries).
  744. 2. Set a widget's OSC **Via** to **USB board (serial)**. Its Ip and Port fold
  745. away (the cable has no address) and a **Board** row appears: pick the port
  746. the board is on. One cable serves the whole of OSCAR, so picking it once
  747. picks it everywhere; there is no separate panel. The old spelling, Ip set
  748. to the word `serial`, still works.
  749. 3. The board's own OSC needs nothing more: what it sends up the cable is
  750. heard beside the network, so a widget with **Data in** on follows it by
  751. address, exactly as it follows the rig
  752. Every widget that sends can be pointed at the cable, and the message is the
  753. same OSC message it would have sent to the network, framed with SLIP -- the
  754. standard way OSC travels over a serial line. `serial` goes in **Ip** rather
  755. than being a section of its own because it changes where the message goes, not what it
  756. is: a slider can send OSC to the board and DMX to a dimmer at once. A board
  757. that talks back is heard like any other OSC in, so a meter with **Data in** on
  758. can show a potentiometer.
  759. The port is opened by the computer running OSCAR, not by the tablet showing
  760. the interface, and it is remembered in `oscar-settings.json`: an installation
  761. that reboots overnight reconnects on its own. So does a cable pulled out and
  762. pushed back in, or a board that vanishes for a few seconds while a sketch
  763. uploads -- OSCAR retries every two seconds until told to disconnect. Nothing
  764. is queued while the cable is out: a level arriving seconds after the gesture
  765. is a light changing with nobody touching it. Choosing the port is editing,
  766. so a locked OSCAR refuses it from other devices; their widgets still reach
  767. the board.
  768. Both sketches parse OSC in about forty lines with no libraries, and
  769. `tools/arduino/README.md` covers what usually goes wrong: the Arduino IDE's
  770. Serial Monitor holding the port, CH340 drivers for clone boards, and the
  771. `dialout` group on Linux.
  772. Two limits. The Windows on ARM build has no serial driver (the `serialport`
  773. release OSCAR uses ships no binary for it): the panel says "No serial support
  774. in this build", and everything else, Wi-Fi boards included, works as usual.
  775. And OSCAR does not use the browser's Web Serial: that opens a port on the
  776. device showing the page -- the tablet, which has no board plugged into it --
  777. and Safari and Firefox do not have it at all.
  778. ## Multiple pages
  779. > Pages are switched off in this version (`PAGES` in `lib/features.js`) while
  780. > publishing and export learn to carry every page. The editor shows one page,
  781. > and a project saved with several shows its first.
  782. An interface can hold more than one page: a page per fixture group, per scene,
  783. or per operator. In the editor, the **Pages** button in the top bar lists
  784. them. Click a name to open that page, **Rename** or **Delete** it from its
  785. row, and add one with the box underneath (leave the name empty and it is
  786. called "Page N"). Two pages cannot share a name, since their tabs could not
  787. be told apart. The last page cannot be deleted. Deleting a page releases
  788. the DMX channels of every widget on it.
  789. On the tablet (`/preview`) the pages appear as a row of finger-sized tabs
  790. along the bottom edge. The interface is made shorter by the height of the bar
  791. rather than covered by it, so nothing on the bottom row of a page sits under
  792. a tab. An interface with a single page has no bar and keeps the whole screen.
  793. The editor's own preview shows the same tabs, so an interface can be tried out
  794. before it is pushed.
  795. Pushing a new layout while a show is running leaves each tablet on the page
  796. it was showing, as long as that page still exists. Every page is locked the
  797. same way: nothing can be dragged, selected or edited from a tablet, whichever
  798. page it is on.
  799. Turning the page lets go of whatever is being held. A momentary button held
  800. with one finger while another taps a tab sends its Value OFF before the page
  801. changes, exactly as if the finger had come up, so nothing is left on because
  802. its button went out of sight. A push does the same.
  803. A widget with Data in on keeps following the rig while its page is not
  804. showing, on a single tablet as much as on several, so a fader opens where
  805. the rig left it rather than where it was last seen, and the next touch does
  806. not jump. What the other tablets do to a widget on a hidden page is
  807. remembered in the same way.
  808. A project with more than one page is saved as project format 3. An older
  809. OSCAR has no way to switch pages and would show only the first, so it
  810. refuses such a file and asks to be updated instead of opening part of a
  811. show. A project with a single page is still saved as format 2, which older
  812. versions open as before.
  813. ## Publishing a working interface
  814. **Publish**, in the top bar, turns the project on the canvas into **one
  815. self-contained page**, separate from the editor, that OSCAR serves at an
  816. address such as `http://192.168.1.20:8080/show/main-stage`. This is the way
  817. onto a **phone or tablet**.
  818. The window opens on the project on the canvas, on a card: its title, who can
  819. open it, the QR code for its address, and one button.
  820. - **Nothing to fill in.** The address is made from the project's title the
  821. first time it is published ("Main stage" is `/show/main-stage`, with a
  822. number added if that is taken) and stays the same from then on. Renaming
  823. the project does not move it, so printed codes keep working.
  824. - **One button, which says what it does.** **Publish** for a project that is
  825. not published yet; **Publish changes** when the canvas is ahead of what phones see;
  826. and no button at all, beside "Up to date", when there is nothing to send.
  827. Saving never changes what phones see; only publishing does.
  828. - **One code.** The QR code is always there, for the address that goes with
  829. who can open the interface. Copy copies the same address.
  830. - **Running on this OSCAR**, the window behind the **RUNNING** pill in the
  831. top bar, lists every published interface, each under its project's title:
  832. who can open it, how many devices are on it, **Edit**, which puts the
  833. project it was published from on the canvas, and a menu with **Download as
  834. a file** and **Take down**. Click a row to see its code.
  835. A published interface remembers the project it was published from, and OSCAR
  836. keeps a copy of that project beside the page: what phones are showing, and
  837. what **File → Revert to the published version** goes back to. A published
  838. page stays reachable while OSCAR is locked.
  839. Each published interface has one setting for **who can open it**. **This
  840. network** is any phone, tablet or computer on the same Wi-Fi, and is what a
  841. newly published interface is. **Off** is no device at all: its address
  842. answers "This interface is switched off", and a phone that had it open is
  843. disconnected. Off closes the door and nothing else, so its schedules and
  844. bridges still run, and it opens again as it was; **Take down** is what stops
  845. those. With OSCAR Pro the same setting has a third answer, **Anyone with the
  846. link**, for phones that are not on your network.
  847. A published page finds OSCAR by the address it was opened at, so it keeps
  848. working if the computer's IP address changes. Unlike
  849. `/preview`, which always shows the last push from the editor, a published
  850. page stays as it was until you publish it again.
  851. **On a phone or tablet.** A served page carries what a phone needs to be
  852. treated as an app of its own, and nothing has to be installed:
  853. - **Add to Home Screen.** On an iPhone or iPad, Share → *Add to Home Screen*
  854. puts the interface on the home screen under the project's name, and it
  855. opens without Safari's bars. On Android, Chrome's menu → *Add to Home
  856. screen* makes the same shortcut; over plain `http`, Android opens it in
  857. the browser, so use the Full screen button there.
  858. - **Full screen.** On a touch screen the page offers a small *Full screen*
  859. button, bottom left. It dims after a few seconds and never goes, so a
  860. control under that corner stays reachable. It is not offered on a laptop,
  861. on a page already opened from the home screen, or on an iPhone, whose
  862. Safari allows no page full screen at all (Add to Home Screen is the way
  863. there).
  864. - **Sleep and wake.** A phone that locks its screen, switches apps or walks
  865. out of Wi-Fi range has its connection closed without being told. When the
  866. page is shown again it checks at once: a connection that is gone is made
  867. again right away rather than after the usual wait, and one that looks
  868. alive is asked for the snapshot and replaced if it does not answer within
  869. a few seconds. Moves made while asleep were never made, as above.
  870. - **Found by name.** OSCAR announces itself on the local network as
  871. `_oscar._tcp`, the way printers do, under "OSCAR on *computer name*", and
  872. answers `GET /show` with the list of interfaces it is serving (name and
  873. address; nothing that is switched off). That is how the OSCAR phone app
  874. lists your OSCAR and its interfaces with nothing typed. It only says "I am
  875. here" on pages that were open to the network already; `OSCAR_NO_DISCOVERY=1`
  876. keeps it quiet. A router that does not pass multicast between its Ethernet
  877. and Wi-Fi sides keeps a phone from hearing an OSCAR on a cable: put the
  878. computer on the Wi-Fi, switch on multicast (IGMP) passthrough on the router,
  879. or scan the QR code in the Publish window, which needs no announcement.
  880. - **Naming a device.** Add `?device=Bar%20left` to the address a tablet
  881. opens, or to the QR code you print, and that tablet is "Bar left" in the
  882. network log and under the device count in the Running window (hover it).
  883. The name is kept on the device for the next open; `?device=` with nothing
  884. after it forgets it. It is a label and nothing more: OSCAR sends nothing
  885. differently for it, and a page could claim any name.
  886. **The canvas yields to the show.** Once a control's id is on a published
  887. interface, moving it on the canvas sends nothing: the published interface is
  888. playing, and two masters on one id would fight on the wire. Every control on
  889. the canvas wears a small light, top right: green, it sends from the canvas;
  890. red, a published interface owns it, and the light's hover text names which.
  891. Controls you add while building stay green, sending from the canvas, until
  892. they are published too, and publishing again makes your edits the show, greening nothing --
  893. ownership simply moves with the copy. The judgement is per control, by id,
  894. so one canvas can hold the show's published controls and half-built new ones
  895. at once.
  896. **Download as a file**, on each published interface in that list, saves the same page as
  897. an `.html` file to host on a web server or open on another **computer**. A
  898. file cannot ask where OSCAR is, so the window that opens is where you say:
  899. the address and bridge port are filled in with what OSCAR reports for itself.
  900. It does not work opened from a phone's own storage: Android and iOS sandbox a
  901. downloaded page and it never reaches OSCAR.
  902. Either way there is nothing to unzip and nothing else to copy. The widgets' settings, OSCAR's runtime, the
  903. socket.io client, the widget styles and your images are all inside it. A file
  904. over about 2MB (a video, usually) stays a link instead, and the dialog names
  905. it so you know it has to travel next to the page.
  906. This is not **See code**, the button beside it. That one shows the markup and
  907. nothing more: a page pasted together from it looks right and sends nothing.
  908. **OSCAR has to be running somewhere the page can reach.** A browser cannot
  909. send OSC or DMX -- it has no UDP -- so the exported page hands everything to
  910. OSCAR's bridge, exactly as the editor and `/preview` do, and OSCAR puts it on
  911. the network. The exported page is a remote for OSCAR, not a replacement for
  912. it. The page says so itself: while it cannot reach OSCAR a banner across the
  913. top says where it is trying and that the controls send nothing, and the same
  914. is written in a comment at the top of the file for whoever opens it in a
  915. text editor. The banner never takes a press meant for the control under it,
  916. and it fades once the bridge answers.
  917. Where OSCAR is gets written into the file when you export. The dialog fills
  918. in the address and **bridge port** this OSCAR reports for itself (the bridge
  919. port is the socket port, 8081 unless you moved it -- not the 8080 the editor
  920. opens on), and you can change both before downloading: use the address other
  921. devices see, not `localhost`, unless the page will only be opened on the same
  922. computer. If OSCAR moves later you do not need to export again. Add the new
  923. address to the page's own:
  924. ```
  925. my-interface.html?oscar-host=192.168.0.20&oscar-port=8081
  926. ```
  927. Things worth knowing:
  928. - **Moves made while disconnected are dropped**, not queued. A tablet that
  929. walked out of Wi-Fi range would otherwise replay every fader position it
  930. passed through, in one burst, the moment it came back.
  931. - The control still moves on screen, so after an outage **the page can show
  932. a position the rig never got** -- a fader at 30 over a light still at 42,
  933. a toggle showing on over a rig that is off. Nothing can reconcile the two
  934. afterwards without being that late burst, so when the connection returns
  935. the page says how many moves were not sent. Move the control again to
  936. send where it now stands.
  937. - "Disconnected" means the page has noticed. A Wi-Fi link that goes quiet
  938. without closing -- a tablet roaming between access points -- looks
  939. connected for some tens of seconds, and a move made in that window can
  940. still arrive late if the link comes back first. `/preview` behaves the
  941. same way; a browser cannot tell sooner.
  942. - **A control whose settings cannot be read stays switched off.** If the file
  943. was edited by hand and a widget's `data-oscar-config` no longer parses, is
  944. missing a setting, or holds a value the editor's settings panel would have
  945. refused -- `"enabled": "false"` in quotes, a Min of `null`, a port of
  946. 70000 -- that widget is dimmed and does nothing, and its tooltip says which
  947. setting. It never falls back to default settings, because the defaults are
  948. a live control aimed at somebody's port 7000.
  949. - Widgets with **Data in** on follow the rig on an exported page, DMX output
  950. works, and several copies of the page -- and `/preview` -- agree on what each
  951. control shows, all through the same bridge.
  952. - **Only the first page is exported** if the project has several; the dialog
  953. says so when that applies.
  954. - A page served over `https://` cannot reach the bridge, which is plain
  955. `http`: browsers block the mix. Open the file directly or serve it over
  956. `http`.
  957. - A locked OSCAR exports only on the computer it runs on, like every other
  958. editing action.
  959. - Running from source, the export needs `npm run build` to have produced
  960. `public/src/runtime.bundle.js`; OSCAR refuses to export without it rather
  961. than hand you a page that cannot send.
  962. The settings are written into the markup only in the exported file. The
  963. project you save never carries a second copy of them.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.