Screens and sound.

What screens there are

var screens = Arda.screens.list();   // answers at once
// [{name: 'customer', w: 800, h: 480, open: true, kind: 'app'},
//  {name: 'HDMI-A-2', w: 1920, h: 1080, open: false, kind: 'video'}]

• kind: 'app' — a window of the app's own, whose document you can write into (below). Today these exist in developer mode, from arda.dev.json's screens.
• kind: 'video' — another monitor of a device, which a camera can be shown on (Cameras). Never a page.
• The screen your app is on is not in the list: it is document.

Writing into another screen

Arda.screens.ready().then(function () {
  var doc = Arda.screen['customer'];          // that screen's Document, or null
  if (!doc) return;                           // this machine has no such screen
  var total = document.createElement('div');
  total.className = 'big-total';
  doc.body.appendChild(total);                // the node moves to the other screen…
  total.textContent = '£12.50';               // …and your reference still works
});

• Wait for Arda.screens.ready() before writing: until then a screen may still show the browser's blank page, and anything appended to it is thrown away.
• Read Arda.screen[name] each time; do not keep it. A window that reloads gets a new document.
• Check for null. A name one machine has, another may not.
• Other screens are send-only. No clicks or events come back. Put anything the person must touch in your own document.
• Until the app writes to it, a screen shows a dark clock with its own name — that is how somebody in the shop learns which screen is which.
• Style it with a <style> element appended to doc.head; your page's stylesheet does not apply there.

A monitor plugged in, unplugged or swapped

Arda.on('screens', function (list) {
  // list = the display connectors as they now are:
  // [{kind: 'drm', name: 'HDMI-A-1', status: 'connected', mode: '1920x1080', monitor: {…}}, …]
  var connected = list.filter(function (s) { return s.status === 'connected'; }).length;
  layOutFor(connected);
  // Arda.screens.list() is already current in here (v1.1.13 and later)
});

The app is told, not restarted. A monitor is recognised by its EDID (monitor.key), not by the socket it is in. Developer mode does not watch your laptop's monitors.

Which screen the app is on

On a device with two monitors, the app goes on the device's Primary screen (portal: the device's Setup tab), or, with none chosen, on the first connected socket. The choice follows the monitor, not the socket. An app may choose too, and its choice is kept:

Arda.screens.controls().then(function (list) {
  var big = list.filter(function (s) { return s.name === 'HDMI-A-2'; })[0];
  if (big && !big.primary) Arda.screens.set('HDMI-A-2', { primary: true });  // the page starts over there
});
// Arda.screens.set('', { primary: false })   back to the system's order

Moving the app restarts the page on the new screen. Check controls() first and do it once, not on every load.

To let an operator pick a monitor for something of your own (a customer display, a camera wall), a select setting with "options": {"device": "screens"} lists each device's connected monitors, keyed by monitor.key. From v1.2.1: see Settings.

Brightness, contrast, scale

From v1.4.0 the same calls reach an Android tablet's screen: controls() lists one screen, named screen, with brightness only (a tablet has no contrast register, and its speakers are Arda.audio's), and set(null, {brightness}) dims it — kept by Android itself on a tablet set up as device owner, so it holds across restarts; the player's own window otherwise, while the player is up.

Arda.screens.controls().then(function (list) {
  // [{name: 'DSI-1', monitor: '…', via: 'backlight', brightness: {value, max, percent},
  //   scale: 100, primary: false, key: '…', onBoot: {brightness: 40}}, …]
});

// Night mode at 22:00: dimmer, now only
Arda.screens.set(null, { brightness: 20 });

// Remember 60 % and set it again at every start
Arda.screens.set(null, { brightness: 60 }, true).then(function (s) {
  console.log('now', s.brightness.percent);   // read back from the screen
}, function (e) { console.warn(e.message); });

• set(name, {brightness, contrast, volume, scale, primary}, onboot). name may be null when there is exactly one screen. Give only what you change. Everything is a percentage.
• A built-in panel (a tablet, a till's own screen) has brightness only (its backlight). An HDMI or DisplayPort monitor is asked over its cable (DDC/CI) and offers what it declares: brightness, contrast, its own speakers' volume. A control the screen does not have is absent, and setting it is refused with a sentence.
• Brightness never goes to 0: 0 % is the dimmest visible step, so a touchscreen can always be woken.
• onboot: true keeps the values on the device and the player sets them again at every start; without it the change is for now only. An operator can forget them on the portal's Device tab.
• scale (50–150, in tens; 100 is as designed) is how big the app is drawn: the page's zoom. It is always kept and the page reloads to take it. At 150 a 1920-pixel-wide screen is 1280 CSS pixels wide, so media queries see the smaller width.
• In developer mode, reads are real where your machine allows; writes never touch your machine and resolve {ok: true, simulated: true}.

Sound: Arda.audio

Arda.audio.get().then(function (outputs) {
  // [{id: 'Headphones', name: '…', control: 'PCM', volume: 40, muted: false, onBoot: {volume: 40}},
  //  {id: 'vc4hdmi0', name: '…', onBoot: {}}]    no volume field: this output has no control
});

Arda.audio.set({ volume: 50 });                       // the first output that has a control
Arda.audio.set({ output: 'Headphones', muted: true }, true);   // and keep it at every start

• Percentages are perceptual: 50 sounds like half, as in alsamixer.
• A Raspberry Pi's HDMI outputs have no volume control: the monitor sets it (through Arda.screens.set(…, {volume}) where the monitor offers it).
• Whether the machine can play sound at all: Arda.device().can.audioOut.

Checked: screens.list() answering synchronously and screens.controls() (a desk's backlight panel and an HDMI monitor) were observed in a local ardaplayer run; names and options are from ArdaJS(). Setting levels, scale and the Primary screen were not verified against a device here.