◀ Back to contents

Preferences

This page covers the preference settings. For why the audio settings decide whether a measurement is trustworthy - bit-exact, exclusive capture and playback - see Theory of operation ▸ Audio backend.

Opened from Tools ▸ Preferences. Live capture and generator playback are paused while the dialog is open, so device or format changes don't tear a running stream; OK applies and saves, Cancel reverts. The window resizes: it opens at its minimum size, and widening it widens the entry fields in place rather than leaving white space. The dialog is organised into five tabs, in this order: Audio, Look & Feel, Oscilloscope, FFT and Frequency response. Audio is the first tab and the one the dialog opens on - it is where a measurement session starts.

Audio

Selects the sound back end and the input / output devices and formats - the settings that decide whether a measurement is bit-exact (see Theory ▸ Audio backend).

The buttons on the backend row

Three buttons share the row with the backend list. Two are always present; the third appears only for a backend that has settings of its own.

Card - per-card calibration profiles

Full-scale calibration - the volts RMS that map to the converter's ±1.0 digital full-scale, and therefore the absolute dBV axis, the scope's voltage readouts and the generator's output level - belongs to the physical card, not to the back end or to the device name a driver happens to report. A card profile ties that calibration to the card itself and follows it across back ends, because the same card shows up under different names - the browser wraps it as Line (...) or Speakers (...), a bench may report the bare name or an ALSA [plughw:...] suffix. A profile keeps a single list of recognized device names - the names and name-fragments that identify this card - so one calibration serves it however the device is spelled.

A profile records, in one place: the card's name; which directions it is calibrated for (Provides: input, output or both); whether it has one channel or two (Channels: Mono or Stereo); how its two channels track each other per direction (Coupling: Linked or Independent); its list of switchable ranges (attenuator / gain / DIP positions); and the measured full-scale of each range - always stored per channel, since no two physical channels are calibrated exactly alike.

All card profiles live in one document in the browser's local storage, under the key phonalyser.devices. It is seeded on first run with ready profiles for a few well-known interfaces (the E1DA Cosmos ADC, the JLsounds I2SoverUSB and the CUBILUX CB5) and everything you edit in this tab is written back to it.

The device store - reading and editing it by hand

The ordinary way to read or edit it is Tools ▸ Devices ▸ Current, which opens the live document in a JSON editor that knows the shape below and will not let an edit through without checking it. Everything this section describes is what you see in that window.

The store can also be reached with the browser's developer tools, which is the raw fallback - no completion, no checking, and a save takes effect only on the next load: open them with F12, go to Application ▸ Storage ▸ Local Storage, select this page's origin and look at the phonalyser.devices row. Use it when you want to copy the whole document somewhere, or to read a store the application will not start on.

The value is JSON: two version markers and one object per card. An annotated store, with every key the application reads:

{
  "formatVersion": 1,        // schema marker - changes only if the schema itself changes
  "contentVersion": 2,       // catalogue generation - drives the once-per-release upgrade merge (below)
  "audioDevices": [          // the list of card profiles
    {
      "name": "E1DA Cosmos ADC",         // logical profile name shown in the Card combo (required)
      "match": [ "E1DA Cosmos ADC" ],    // recognized device names: substrings (case-insensitive) that identify this card
      "input": {                         // a per-direction block - "output" is the same shape
        "channels": "INDEPENDENT",       // MONO = one channel; LINKED = two channels, shared range switch; INDEPENDENT = two channels, each its own
        "ranges": [                      // one row per front-end position (attenuator / gain / DIP)
          { "label": "1.7V", "fsVrms": { "left": 1.7, "right": 1.7 }, "calibrated": true },   // measured full-scale per channel; calibrated = you measured this row (upgrades never overwrite it)
          { "label": "3.5V", "fsVrms": { "left": 3.5, "right": 3.5 } }                        // a range you have not yet calibrated - still the seeded nominal
        ],
        "activeRange": { "left": "1.7V", "right": "3.5V" }   // INDEPENDENT: a { left, right } map, each channel's own active row
      }
    },
    {
      "name": "I2SoverUSB",
      "match": [ "I2SoverUSB", "JLsounds" ],
      "output": {
        "channels": "LINKED",
        "ranges": [ { "label": "default", "fsVrms": { "left": 2, "right": 2 } } ],
        "activeRange": "default"         // LINKED / MONO: a single label (both channels switch together)
      }
    }
  ],
  "bindings": {                          // device -> card choices you made in the dialog; omitted entirely while nothing is bound
    "Line (E1DA Cosmos ADC)": "E1DA Cosmos ADC"   // this exact device name always resolves to this card, whatever "match" would say
  }
}

The // comments above are explanation, not part of the document - JSON has no comments, so a value you paste back must not contain them.

What the keys mean:

• match is the Recognized device names list from the card editor: each entry is matched as a substring (case-insensitive) against the device name the driver reports, and when several cards could match, the most specific (longest matching) entry wins. This is the guess, used when you have not said which card a device is.
• bindings is the map of choices you did make: picking a card in the Card combo records the selected device's name against that card here. A binding is consulted before the match rule, so a card that merely recognises part of a device's name can no longer overrule the one you picked - which is what used to happen with two interfaces whose names share a word. A binding naming a card that has since been deleted or renamed is not an error: it falls through to ordinary matching, so a stale entry can never leave a device uncalibrated. The block is left out of the file entirely while nothing is bound. The same OK also appends the device's exact name to that card's match list as a visible alias, so you will see the name in both places - the bindings entry is the one that decides.
• fsVrms is the range's full-scale in volts RMS. The application always writes the { left, right } pair - each channel carries its own measured value - though a single number applies to both sides if you type one by hand.
• "calibrated": true marks a row you actually measured through a Calibrate flow; the upgrade merge never overwrites it. A row without the flag is still the seeded nominal.
• "calibrationFromDevice": true (add it inside the input or output block) marks a card whose full-scale is reported by the instrument itself (a QA40x-class device): its ranges stay switchable, but the app never writes calibration into them and their full-scale values are read from the device itself, not delivered by a catalog upgrade. Omit the key for an ordinary card you calibrate yourself.
• activeRange is the selected row. INDEPENDENT uses a { left, right } map (each channel its own row); LINKED and MONO use a single label.

Editing it in the developer tools has one rule the built-in editor does not: do it with the application's tab closed, then reopen the page. The store is read once at start-up and rewritten whenever the app saves, so an edit typed into storage while the app is running is simply overwritten. The JSON editor has no such problem - it hands the document to the running application itself, which is why its changes take effect at once. Entries with no name (or ranges with no label) and unrecognised keys are skipped with a warning in the console rather than aborting the load, so a small mistake costs one entry, not the whole store. Deleting the phonalyser.devices key makes the next load re-seed the built-in defaults, which loses any cards you added or calibrated.

A stored document that exists but cannot be parsed at all is never silently replaced by defaults. In the browser these are entries in the page's local storage, not files on disk, so the quarantine is a copy under a new key rather than a file beside another: the unreadable value is copied to <key>.corrupt and the failure is logged, so what survives in it can still be recovered - read it out with the browser's developer tools - and the next save cannot overwrite the evidence. This covers the settings document and the device store alike. Local storage is per browser and per origin: clearing site data for this page discards both, and they do not follow you to another browser or another machine.

Upgrades never lose your work. The seeded catalogue carries a contentVersion; when a new release ships a higher number the merge runs once, then records the new number so it never repeats. For each catalogue card it finds your matching card - by name or by a shared recognized-name entry, so a card you renamed is still found - and reconciles only its range table: a range the release added appears in your store, and a range you both have is refreshed to the release's nominal full-scale - except a range you calibrated, which keeps its measured value and its calibrated flag. A card that is entirely new in the release is added whole. Everything else is yours and is never touched: your calibrated values, the cards and ranges you added by hand, your recognized-name list, your channel modes and your active-range selections all survive.

Each direction - Input and Output - carries its own Card combo above its device controls. Bind a card profile when you want any of:

• several interfaces you switch between, each with its own full-scale;
• one interface with a switchable analog front-end - an attenuator, an input-gain step or a DIP setting - where each position has a different full-scale;
• the same card reached under more than one back end, so a single calibration is reused instead of re-measured per back end.

A plain sound card with a fixed front-end needs no profile - leave its Card selection empty and it behaves exactly as before this feature existed, drawing on the single shared full-scale that predates card profiles.

The Card combo and the edit button

The combo lists every card profile that has at least one range in this direction - the pre-seeded known cards included - plus New card...; a device with no card shows an empty selection. A small pencil (edit) button beside the combo opens the card editor for the selected card.

The combo re-resolves automatically whenever the device changes: the app matches the new device name against every card's recognized-name list and, when one correlates, selects it and shows its ranges. When more than one could match, the most specific (longest matching) recognized name wins. Selecting the combo entry and pressing OK is what binds the device, and it does two things at once: it records the device->card choice in the store's bindings map - which is what resolves the device from then on, ahead of any name matching - and it appends the device's exact name to that card's recognized-name list as a visible alias. A device is never bound to two cards at once, and it is the bindings map that guarantees it: there is exactly one entry per device, so re-binding to another card replaces that entry. The alias left behind in the previous card's list is not removed - but it no longer decides anything, and the device follows the new card.

When no card matches the device, the app does not bind one silently: it offers to make one - Create a new card for '<device>'? - and on yes opens the card editor pre-filled from the device name. You can also pick New card... yourself, or leave the selection empty to keep the device unbound.

Leaving the selection empty keeps the device unbound: it falls back to the single shared full-scale that predates card profiles, and the range table stays hidden. That global calibration survives only for the current session and is never written back to the settings document - a document from before 1.2 is still read once, and the entries disappear with the first save. The cards in the device store are the persistent home of every full-scale value, so bind every measurement device to a card. Selecting New card... creates a profile whose first range is seeded from the calibration currently in effect, so the new card starts already calibrated to wherever you were.

The card editor

The pencil button opens the card editor, a small dialog holding every property of a card except its per-range voltages (those come only from the Calibrate flows).

The Input and Output groups grey out to match Provides - an input-only card shows its Output group disabled, and vice-versa.

Ranges table

A range is one setting of the card's analog front-end - an attenuator step, an input-gain position, a DIP or relay setting - each with its own full-scale voltage. The table lists one row per range:

The row carries no full-scale voltage field. A range's full-scale value is not typed here - it is set exclusively by running the crosshair Calibrate flow with that range marked active, which writes the measured full-scale into it.

A plain card that never changes its front-end keeps a single row. A switchable interface gets one row per position, and you flip the active marker whenever you change the hardware.

How many active columns the table shows follows the card's Channels and per-direction Coupling, both set in the card editor:

• Independent stereo card - the active marker splits into two columns, headed Left and Right, each carrying exactly one active range and its own editable label, so the two channels track their own front-end position separately. This is the E1DA Cosmos ADC, whose left and right DIP switches move independently: set the left column to the range that matches the left DIP and the right column to the range that matches the right. The bundled Cosmos card ships in this form with every DIP position listed, so its range table opens with both columns present.
• Linked stereo card, or a Mono card - a single active column, so both channels switch ranges together. (A Linked card still calibrates each channel separately - only the range selection is shared.)

A QA40x input range is not the dBV it is called

For a QA402 / QA403 - on this machine or on a bench across the network - every input row carries a second label after the plain one:

0 "dBV" real 0 dBFS or -9 dBV

It is there because the analyzer's range names are not RMS voltages, and reading them as such is off by about 9 dB. A QA "N dBV" input range is an N dBFS reference measured peak-to-peak across the differential pair; the RMS full-scale voltage that corresponds to it sits roughly 9 dB lower - a factor of 2 for peak-to-peak versus peak, and √2 for peak versus RMS, is 2·√2 ≈ 9.03 dB. So the range the analyzer calls 0 dBV is a full scale of about −9 dBV RMS, and that is the number every volt, dBV and derived figure in this application is computed from.

Three things follow. The second label is display only: the stored card keys, the range radios and the values written into the device store keep the plain N dBV, so nothing in your store changes because of it. The output ranges are left alone - those are genuine dBV, with no hidden peak-versus-RMS term. And a loopback measurement of a QA40x reads its own generator about √2 (3 dB) louder than the level asked for, which is not a fault in either direction but the balanced output driving a differential input; see Theory ▸ The QA40x analyzer backend.

Worked example - two cards on one bench

A typical bench has an E1DA Cosmos ADC on the input, whose DIP attenuator switches its full-scale, and a separate JLsounds card in use as well. Bind each once and their calibrations never cross:

1. Select the Cosmos in the input Device combo. Its Card combo pre-selects the known card E1DA Cosmos ADC - a ready profile seeded into the device store - with a nominal range for every DIP position, 1.7V up to 43V, already in place. Confirm it by selecting it and pressing OK. (For an unrecognised card you would instead choose New card... and add the rows by hand.)
2. Because the Cosmos DIPs move per channel, its table shows a Left and a Right active column. In each column mark the range that matches that channel's DIP position - the two columns track the two switches independently.
3. Calibrate those ranges through the crosshair Calibrate flow - on the scope only the row for the currently measured channel is live (the other row is disabled and stays empty), writing that channel's measured full-scale into its active range; measure the other channel to calibrate its row in turn (the FFT's own Calibrate likewise writes only the channel being analyzed). Then flip a DIP, switch that channel's active column to the other row, and calibrate again; the new measurement lands in that channel's second range.
4. Later, select the JLsounds device: it carries its own card and its own calibration, untouched by the Cosmos.

Because flipping the DIP means nothing more than switching which range is active, and the values follow the card rather than the back end, switching between the two cards - or reopening the Cosmos under a different back end once its name is bound there - never mixes their full-scales up.

How calibration writes into a card

The crosshair Calibrate flows anchor the scale against a known reference - the scope and FFT ADC calibration for the input, and the generator DAC calibration for the output. Each writes the measured full-scale into the active range of the card the device resolves to. If the selected device has no profile yet, the first calibration creates one automatically - logical name from the device, a recognized-name entry for it, and one seeded range - so you get a card profile simply by calibrating, without visiting this tab first.

Calibration is always per channel. A Stereo card opens the shared two-row dialog with a Left and a Right field, because no two physical channels are calibrated exactly alike - coupling shares only which range is selected, never the measured values; a Mono card shows a single row. On the scope ADC path only the row for the currently measured channel is live - the other row is disabled and stays empty, so you calibrate one channel at a time; on the FFT ADC path only the row for the channel being analyzed is enabled, since the FFT works one channel at a time; the DAC path drives both rows. Each row writes only its own channel's active range.

When the values take effect

The card's active-range full-scale is resolved - by the bindings entry for the device if you made one, otherwise by the match rule - and applied at these moments: when capture starts (input), when the generator starts (output), and when you close this dialog with OK. From that point the resolved value drives the FFT's absolute dBV axis, the oscilloscope's voltage readouts and the generator's output scaling.

Two cases fall back to the single shared full-scale that predates card profiles: a device that resolves to no card at all, and a card whose active range is still uncalibrated - a row holding zero is an empty row, not a measurement, so it contributes no calibration of its own. That shared value is runtime state only: it is no longer written to the settings document (a document from before 1.2 is still read once, and the entries disappear with the first save), because saving it would store the last calibrated card you selected as the machine-wide default and hand it to the next uncalibrated device as though it had been measured there. The persistent home of every full-scale value is the device store - the cards.

Because an uncalibrated selection measures on a nominal placeholder rather than on your hardware, closing this dialog with OK after changing the backend or either device warns you once when the committed selection has no calibration behind it, naming the input, the output or both. A device that reports its own full-scale (calibrationFromDevice, a QA40x-class instrument) is exempt - there is nothing for you to calibrate.

A value also takes effect immediately when you close the calibration dialog with the Calibrate button: the new full-scale is written into the device store and applied through the live card binding to every consumer - the oscilloscope's scaling, the FFT's dBV axis and the generator's amplitude ceiling - without a restart.

Measuring through a Phonalyser server

The hardware does not have to be wired to the machine you are sitting at. The desktop Phonalyser running as a server on the machine that is wired to the converters turns it into a bench, and this application then measures through it: you pick one of the bench's backends in the list above and everything - devices, formats, cards, calibration, the generator, the sweeps - works as though the hardware were plugged in here. For what happens on the wire, see Theory ▸ A bench across the network.

The server list

The Servers... button on the backend row opens Phonalyser servers. The list starts empty, and one address fills it. A browser cannot listen for the announcements servers broadcast on the local network - a page has no way to receive them - so nothing arrives by itself the way it does on the desktop. Instead you type the address of one server in the row at the bottom of the window, and it reports every other server it has heard: its peer table is the whole of discovery here. One reachable bench, and the room appears.

The table has three columns:

Three buttons sit under the table. Connect and Remove act on the selected row; Disconnect does not - there is only ever one session, and that is the one it ends.

Below the buttons sits Add a server by address - a Host: field, a Port: field and an Add button - and a Close button:

Choosing a bench backend

A connected server's backends join the Backend list beside the local ones, written <server> -> <backend> - e.g. bench-pc -> QA40x. Only backends the bench can really operate are offered: one that is in the server's build but cannot run on that machine is left out rather than shown greyed.

• Device, sample rate and bit depth are remembered per server and per backend, exactly as they are for a local backend, so switching between two benches - or between a bench and the card on your desk - does not cost you the format you had set. An older settings document reads unchanged, and entries written by a newer release, or for a server this installation has never met, survive a save untouched.
• A device another operator is using says so. Each of the bench's devices may be held exclusively by one client at a time, and one that is taken reads <device> - in use by <client>, naming the machine holding it. A device this installation holds reads normally - your own running scope is not news.
• Browsing the list only previews. Selecting a server's backend fills the device combos from that bench without committing anything, so looking is free; Cancel puts the previous routing back untouched and OK is what commits.

Cards and calibration on the bench

Calibration belongs to the hardware, so with a bench backend selected the Card section works against the bench's store rather than this machine's:

• the Card combo lists the bench's cards;
• a crosshair Calibrate writes the measured full-scale into the bench's store, where it belongs and where every other operator of that bench benefits from it;
• and when you select a bench device that has no calibration while this machine holds a calibrated card for it, you are asked whether to copy it over - Copy calibration to the server? - once per session and never silently. Say no and nothing is written.

What else crosses the wire

• A backend's own settings. QA40x preferences and the input and output range radios drive an analyzer on the bench exactly as they drive a local one, live telemetry included - the panel reads whichever analyzer the selection points at.
• The generator runs on the bench. It is commanded, not streamed: this application tells the bench what to emit and the bench's own DAC renders it. That is what keeps a frequency-response sweep honest - it is deconvolved against exactly what the bench played, with the sweep's first sample marked in the capture stream itself.
• A rate the bench cannot give you. If the device grants a different sample rate than the one you asked for, a live capture runs and is displayed at the granted rate - the frequency axis follows the reality - while a sweep is refused rather than deconvolved against a rate that was never played.
• File playback crosses too. The chosen WAV / AIFF / FLAC is uploaded once - up to 50 MB, the limit the server enforces, checked here before a byte leaves - and the bench decodes and plays it out of its own DAC, at the file's own rate and depth. In loop is honoured at the far end, Stop reaches across, and the play indicator goes out when the bench says the file ended rather than when you press stop. The upload lives in the server's memory and is dropped when the connection closes, so nothing accumulates on the bench.
• A refusal reads like a local one. A device the bench will not open comes back as the same six reasons a local failure has, in your own language.

Editing the settings as JSON

Both of the documents this dialog writes - the settings and the card profiles - can be opened directly, as text, from the Tools menu, in an editor that knows their shape and explains every key. That has a chapter of its own: Editing the settings as JSON.

Look & Feel

Oscilloscope

FFT

Frequency response