Settings

Open from the menu: Settings. Press Save when finished. Settings are stored in %AppData%\OscarWatch\settings.json on Windows, or ~/.config/OscarWatch/settings.json on Linux and macOS.

Station

Your operating position: display name (for labels in pass tools), latitude, longitude, Maidenhead grid, and height above sea level in metres. The grid square is normalised to uppercase as you type. Accurate height helps slightly with geometry; position is essential for passes and az/el.

The display name is shown in pass planner, mutual pass, visualisers, and calendar export — for example “Home” or “Portable”. It is not your on-air callsign. For logging identity, set My callsign on each OscarWatch Logbook when you create it.

Horizon mask (optional) — open Edit horizon mask… to draw your local skyline (trees, buildings, hills) on a polar editor: click to add points, drag to move, right-click to remove, or edit the az/el table. An empty mask means unused; pass prediction and plots still use Tracking → Minimum elevation alone. When points are set, visibility at each azimuth uses the higher of the mask and that minimum. The mask does not command the rotator; that is Rotator → Start tracking at elevation. The same mask is stored per station profile (Settings and Pass planner) and is drawn on the sky plot and pass polar plots.

TLE

Choose where pass times and orbital positions come from. The transponder frequency database is separate — see Transponder database.

OscarWatch (tle.oscarwatch.org) — default AMSAT-oriented JSON GP catalogue (recommended).
AMSAT.org (JSON GP bulletin) — daily bulletin from newark192.amsat.org.
Custom URL — any HTTP(S) address that returns JSON GP elements or classic three-line TLE text (for example Celestrak amateur-group TLEs with FORMAT=json or FORMAT=tle).
Local file — browse to a .json, .txt, or .tle file on your PC; use Browse… to pick it.
TLE updates — when to download fresh data automatically (OscarWatch and custom URLs only). Local files are re-read when you save Settings or use Satellites → Refresh TLEs.

Changing the source and pressing Save reloads the catalogue. The status bar shows which source is active (for example “TLE 2 h ago (tle.oscarwatch.org)”).

Tracking

Minimum elevation — passes below this angle are hidden from predictions and from the pass elevation timeline below the map. When a horizon mask is set, each azimuth uses the higher of the mask and this value.
Prediction hours — how far ahead to compute passes.
Check for transponder database updates on startup — downloads tle.oscarwatch.org/satellite_database.json when the app opens and offers to merge new satellites/modes (on by default). Use Satellites → Update transponder database… to check manually.

Appearance

Settings are grouped into Locale & time, Map, Theme, and Updates.

Locale & time

Language: English (UK) is the default UI language (British English spelling and en-GB date/time formatting). Japanese, Portuguese (Brazil), Simplified Chinese, Spanish, Thai, Indonesian, Russian, German, and Italian are also available. A language change requires restarting OscarWatch.

Clock format — 12-hour (AM/PM) or 24-hour for times in the app.

Times shown in — local time (your PC time zone) or UTC for the main window: status clock, sidebar pass list, pass elevation timeline, hams.at roves, and sunlight prediction. Pass planner and mutual pass have their own local/UTC control so you can check UTC there without changing this setting. Satellite tracking always uses UTC internally.

Map

Show footprint motion arrows — optional arrows inside satellite footprints on the world map indicating ground-track direction (on by default).

Show day/night greyline on map — shades the night side of Earth and draws the terminator; footprints stay on top. Follows map time when you scrub.

Show next-orbit ground track — faded line for the focused satellite's next orbit behind the current track on the world map (on by default).

Map centre longitude — Greenwich (default mid-Atlantic view), your station gridsquare, or a custom longitude (−180° to 180°). Footprints and tracks wrap at the map edges in all modes.

Theme

Light, dark, or follow the OS setting. The sky plot follows the theme; the world map image stays light for readability.

Updates

Check for application updates — compares your version with the latest release on GitHub on startup and daily while running. You can also check manually from Help.

Voice

Optional spoken alert when a satellite rises above a set elevation (e.g. “Alpha Oscar Zero Seven is rising”). Choose a voice and test it. On Linux, install espeak-ng (recommended) or legacy espeak; speech-dispatcher with spd-say is also supported if eSpeak is not installed.

Scheduled passes

Mark specific passes as Scheduled in Upcoming Passes or Pass Planner. While OscarWatch is running, each scheduled pass can play a ding and show an alert window a configurable number of minutes before AOS. Use Test sound to check the ding. The ding is the same generated tone on Windows, macOS, and Linux (system player, ffmpeg, or PortAudio as available). This is separate from voice rising announcements (which follow elevation for all enabled satellites).

Recording

Optional automatic audio capture from a line-in or USB audio device while you work a pass. Open Settings → Recording to configure it.

Enable automatic pass recording: turn recording on or off.
Input device: choose the audio input that carries your radio audio (sound card line-in, USB interface, etc.). The selection is remembered by device name across restarts (USB cards often change PortAudio index after reboot). Press Refresh if you plug in hardware after opening Settings; re-select only if the OS renames the device or it is missing from the list.
Sample format: mono 44.1 kHz is a good default for FM/SSB; stereo if your interface requires it.
File format: WAV (always works) or MP3. MP3 needs ffmpeg installed so OscarWatch can find it on your PATH. Capture is still WAV first; OscarWatch converts when the pass ends and deletes the intermediate WAV on success. If ffmpeg is missing or conversion fails, the WAV is kept.
Start / stop elevation: recording begins when the focused satellite rises through the start elevation, and stops when it falls below the stop elevation. Keep stop at or below start to avoid flapping near the threshold.
Output folder: leave blank to use the default (%APPDATA%\OscarWatch\recordings on Windows, ~/.config/OscarWatch/recordings on Linux, ~/Library/Application Support/OscarWatch/recordings on macOS). Pass recordings are kept until you delete them; OscarWatch does not auto-prune audio files. Settings shows the current file count and total size for that folder, with an Open folder button. You can also use Help → Open recordings folder.
Test recording (5 s): saves a short clip so you can confirm levels and device selection before a pass.

Other Settings tabs open immediately. The Recording tab loads audio devices when you select it. On some FlexRadio setups with DAX virtual audio devices, PortAudio can hang or fail while SmartSDR for Windows is running (OscarWatch itself talks to the radio over the API, not via that GUI). OscarWatch checks audio in a separate probe process first so a DAX failure does not close the main application. If the Recording tab reports that audio is unavailable, configure recording with SmartSDR for Windows closed, or use Refresh on the Recording tab after closing DAX streams you do not need.

Files are named in UTC: {satellite-name}-{yy-MM-dd-HH-mm}.wav or .mp3 (for example so-50-26-05-24-14-30.wav). Only the satellite you have selected on the map or pass list is recorded. If you switch to another satellite that is already above the start elevation, recording begins straight away. While recording, a red REC badge appears on that pass in the sidebar.

WAV files are uncompressed (~5 MB per minute mono at 44.1 kHz). MP3 is much smaller when ffmpeg is available.

Installing ffmpeg for MP3 recordings

OscarWatch does not bundle ffmpeg. You only need it if you choose File format → MP3. After installing, close and reopen OscarWatch (or reopen Settings → Recording) so it can see ffmpeg on your PATH. The Recording tab should say that ffmpeg was found.

Check that it worked by opening a terminal and running ffmpeg -version. You should see version text, not “command not found”.

Windows

Open Windows PowerShell (Start menu → type PowerShell → Open).
Run:
```
winget install ffmpeg
```
If winget asks you to agree to source or package terms, accept them.
Close PowerShell, then fully quit and restart OscarWatch.
Optional check: in a new PowerShell window, run ffmpeg -version.

If winget is not available on older Windows builds, install App Installer from the Microsoft Store, or use Chocolatey with choco install ffmpeg.

macOS

Install Homebrew if you do not already have it (the brew.sh site shows the one-line install command).
Open Terminal and run:
```
brew install ffmpeg
```
Quit and restart OscarWatch, then open Settings → Recording and confirm ffmpeg is found.
Optional check: run ffmpeg -version in Terminal.

Linux

Use your distribution’s package manager (examples):

Debian / Ubuntu / Mint:

sudo apt update
sudo apt install ffmpeg

Fedora:
```
sudo dnf install ffmpeg
```
Arch:
```
sudo pacman -S ffmpeg
```

Then restart OscarWatch and confirm Settings → Recording reports that ffmpeg was found. Optional check: ffmpeg -version in a terminal.

Rotator & Radio

See Radio & rotator overview for rig type and wiring; Linux serial ports if ttyUSB numbers change after reboot; Doppler thresholds (FM vs SSB/CW ballpark values), resume CAT after you spin the dial, adaptive and lead, and rotator options.

Serial port — on Windows, pick the COM port from Device Manager. On Linux and macOS, pick or type the device path (for example /dev/serial/by-id/… or a udev alias such as /dev/USB821H or /dev/ttyICR9K). Press Refresh after plugging in USB. Each radio, rotator, and serial GPS must use a different port.

Under Radio, Linear CW: keep receive in USB/LSB (transmit CW only) controls how CAT and Cloudlog set modes when the frequency panel is on CW for linear SSB satellites (see Frequencies).

Integrations

The Integrations tab groups optional hardware and external services: GPS, hams.at Upcoming Roves, OscarWatch, Cloudlog, QRZ, HamQTH, and Satellite link. Pick a section from the list on the left.

GPS

Choose Serial (COM port) for a USB or serial GPS on its own port (not shared with the radio or rotator), or gpsd (network) when a gpsd daemon on your LAN (for example on a Raspberry Pi) already manages the receiver.

Enable GPS — turn GPS integration on or off.
Connection — Serial reads NMEA GGA / RMC sentences; gpsd uses the JSON watch stream on TCP port 2947 (host + port configurable).
Serial port / baud rate — when using serial, match the GPS (often 4800 or 9600 8N1). Press Refresh if the port list is stale. On Linux, prefer a stable by-id or udev path — see Linux serial ports.
gpsd host / port — hostname or IP of the machine running gpsd (often 127.0.0.1 on the same PC, or your Pi’s LAN address).
Refresh status — shows connected / waiting for fix / fix with lat/lon and satellite count.
Apply fix to station — copies the current fix into Settings → Station (latitude, longitude, grid, and optionally altitude).
Automatically update station position from GPS fix — keeps your QTH in sync while roving (saves periodically).
Update altitude from GGA — when auto-update is on, applies height from the GGA sentence.
Use GPS UTC for satellite tracking — pass predictions and live tracking use GPS time instead of the PC clock. Does not change the Windows system clock.
Use GPS time for FT4 slot timing (on by default): while the GPS has a fix, FT4 compares GPS time with the PC clock. If the PC is more than a quarter of a second out, the FT4 window times its slots from GPS instead. Useful in the field with no internet time sync. Does not change the Windows system clock.
Minimum satellites for fix — ignore fixes with fewer satellites in view (default 3).

With GPS enabled, the status bar shows GPS in green when a fix is active and red when GPS is on but there is no fix. If Use GPS UTC is checked, GPS Time appears the same way (green when tracking is using GPS UTC).

hams.at

Enable the integration, paste your hams.at API key (Bearer token), and set how often roves refresh. Your key is stored locally in settings.json like other credentials. Use Test connection to verify the key. Set your observer location on hams.at so is_workable alerts match your station.

OscarWatch

Enable reporting, set the base URL (default https://oscarwatch.org), and paste an API token from oscarwatch.org Settings → API tokens. Your website profile must include a callsign and gridsquare before reports are accepted. Use Test connection to call GET /api/v1/me. When enabled, the frequency overlay shows a Report button so you can submit On / Off / Telemetry only for the focused satellite and selected mode. Optionally enable Automatically report On when logging a QSO: each new live QSO posts an On report using the QSO time and the focused satellite’s catalogue mode (edits do not re-report). Manual and automatic reports require elevation of at least −1°. When the integration is enabled, OscarWatch also fetches public community status (no API token required for reading): a chip on the frequency overlay for the selected mode, and a colour dot on Upcoming Passes rows (tooltip lists each mode). Offline or failed fetches hide those indicators without blocking tracking. OscarWatch FT4 can send decode spots with this same API token. The OscarWatch tick on the FT4 settings Reporting page stays unavailable until the token is saved. Spot sending does not need satellite status reporting to be turned on.

Cloudlog

If you use Cloudlog, enter your server URL and API key. Click Test connection after both fields are filled — OscarWatch loads your available logbooks (logbooks must have a public slug in Cloudlog) and shows a Logbook dropdown. Pick the logbook to use for grid lookups on hams.at roves.

While tracking, OscarWatch posts current satellite uplink/downlink frequencies to the Radio API when they change, and repeats the same state on a keepalive interval (default 10 minutes). Configure Radio name and keepalive below the logbook. Use Test connection before relying on live updates in the field.

Highlight grids I still need on hams.at roves (shown when a logbook is selected) checks each rove grid against that logbook using Cloudlog’s logbook_check_grid API with band: SAT, so only satellite QSOs count. Grid badges on rove rows are described in Map & sidebar → Rove grid badges.

QRZ

Optional callbook lookup for OscarWatch Logbook. Enable it, enter your QRZ username and password, then use Test connection. Credentials are stored locally in settings.json like other API keys. Filling first names from QRZ uses the QRZ XML Data service, which needs a QRZ XML subscription. Lookups run after you type a complete callsign; they do not overwrite a name you already typed or one recalled from a previous QSO in that logbook. Timeouts and missing records fail quietly so logging stays fast.

The same username, password, and enable switch are also on OscarWatch Logbook → Settings → QRZ.

HamQTH

Optional fallback callbook for OscarWatch Logbook. A free HamQTH XML account is enough (no paid subscription). Enable it, enter your HamQTH username and password, then use Test connection. When QRZ is off, misses a call, or is not configured, OscarWatch asks HamQTH for the operator’s first name or on-air nickname, and, if Grid is empty, their locator. The same fields are on OscarWatch Logbook → Settings → HamQTH.

Satellite link

Broadcast focused satellite name, frequencies, modes, and tracking data to logging applications over a local WebSocket. This replaces the legacy SatPC32 DDE interface for third-party software. Full operator and developer documentation is in Satellite link.

Enable — starts the WebSocket server (default port 7373).
Allow connections from local network — off = this PC only; on = any LAN client. On Windows, allow OscarWatch when the system firewall prompt appears.
Only broadcast when satellite is above horizon — sends ** NO SATELLITE ** when elevation ≤ 0°.
Update interval — throttle for unchanged payloads (default 1 s); focus/mode changes are immediate.

The status bar shows Sat link when enabled (waiting, client count, or error).