swl

swl is a lightweight, command-line AM DX / SWL logging and station-suggestion tool.

It is designed for:

• nighttime medium-wave DX listening
• SSH / terminal-based workflows
• editable, future-proof logs (Markdown + YAML)
• no database, no GUI, no heavy dependencies

The philosophy is:

Capture what you heard, suggest what it might be, confirm when you know.

License: MIT

---

Features (current)

• FCC-derived AM station cache (530–1700 kHz)
• Distance/bearing-aware station suggestions
• Day / night–aware ranking (--when auto|day|night)
• YAML + Markdown log entries (human-editable)
• Automatic timestamping (UTC + local)
• Optional weather + space-weather snapshot
• Structured confirmation via match: field
• Works cleanly over SSH, e.g., via Termux (low RF noise setups)

---

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

---

First-time setup

View or create config

swl config

This creates (if missing):

~/.config/swl/config.yaml

---

Station cache

Build / refresh the FCC station cache

swl stations update

Force refresh:

swl stations update --force

Override the FCC URL (advanced):

swl stations update --url "https://transition.fcc.gov/fcc-bin/amq?...&list=4"

---

Suggesting stations

Basic suggestion

swl suggest 760

What “auto” means

--when auto (default) uses sunrise/sunset logic of the config location to determine day or night.

Force night or day behavior

swl suggest 760 --when night
swl suggest 760 --when day

Wikipedia links

suggest inserts unverified Wikipedia hyperlinks to the call sign in the terminal table (OSC 8). Default suggest behavior will also reproduce these bare links in a simple list under the table. To omit this second listing, use --nowiki.

---

Logging receptions

Log an unidentified station (most common DX workflow)

swl log 1120 --tag unid --note "Weak Spanish talk, possible sports"

This creates a Markdown file with:

• timestamps
• conditions
• candidate list
• editable notes

Log a known station (confirmed at creation time)

swl log 1000 --match KCEO --tag catholic --note "Daily Mass"

This immediately sets a structured match: entry.

Back-date a log entry

swl log 640 --at "2026-02-01 02:15"

Interpret timestamp as UTC:

swl log 640 --at "2026-02-01T02:15Z" --utc

Open editor immediately after creation

swl log 760 --edit

Note: current behavior using --edit may not capture --match as this is a secondary edit.

---

Confirming stations (swl match)

Confirm a previously logged UNID

swl match path/to/log.md --callsign WJR --freq 760

Overwrite an existing match

swl match path/to/log.md --callsign KFI --freq 640 --force

What match writes

match:
  callsign: KCEO
  facility_id: 34459
  frequency_khz: 1000
  city: SAN DIEGO
  state: CA
  country: US
  dist_km: x.xx (based on config location)
  bearing_deg: xxx (based on config location)
  power_day_w: 5000
  power_night_w: 5000

This enables later analysis without parsing free-text notes.

---

Log file format

Each log is a standalone Markdown file:

---
ts_utc: 2026-02-01T02:35:12Z
ts_local: 2026-01-31T18:35:12-08:00
freq_khz: 760
mode: AM
candidates:
  - callsign: WJR
    community: Detroit
    state: MI
    dist_km: 3070
    bearing_deg: 63
    score: 0.72
match: null
tags:
  - unid
---
Heard male talk with music. Possible ID at :58.

You are encouraged to edit these files by hand, for example through the --edit feature while still listening.

---

Typical workflows

Nighttime DX session

1. Tune unfamiliar signal

2. Run:

   swl suggest 760 --when night

3. Log (both unmatched and matched):

   swl log 760 --tag unid --tag politics --tag news --note "News report of today."

   swl log 760 --match WJR --tag politics --tag news --note "News report of today."

4. Later, confirm if not previously matched:

   swl match <logfile> --callsign WJR

---

Planned upgrades

Near-term (already designed)

• swl find (search logs by freq, tag, callsign)
• swl stats (most-heard freqs, confirmed stations, etc.)

Medium-term

• Audio recording attachment to logs
• Directional vs nondirectional hints
• Better night/day facility weighting
• Export formats (CSV, ADIF-like)

Explicitly not planned

• GUI
• SQLite / heavy database
• Automatic “you are hearing X” assertions

---

Design principles

• Human-readable first
• Editable logs
• Authoritative data sources
• No hidden state
• SSH-friendly