seedlink-grab

Download time windows of miniSEED from a SeedLink station and plot the waveforms. Built for the Nanometrics Centaur embedded SeedLink server (multi-station handshake), reached directly over the network.

--host is required (no default; or set SEEDLINK_HOST). --port defaults to 39962. The examples below use the public INGV SeedLink server discovery.ms.ingv.it:39962. Other servers may listen on a different port — pass --port accordingly; a wrong port shows up as Connection refused.

Build

docker build -t seedlink-grab .

Download + plot

--net, --sta and --cha are required; --loc is optional (omit for any location). --cha takes one or more channels separated by , or . (e.g. HHZ,HHN,HHE or HHZ.HHN). Window is origin - before to origin + after (seconds); --plot renders a PNG.

docker run --rm -v "$PWD/data:/data" \
    seedlink-grab download \
    --host discovery.ms.ingv.it --port 39962 \
    --net IV --sta MSSA --cha HHZ,HHN,HHE \
    --origin 2026-06-15T12:00:12 --before 10 --after 30 --plot

Output goes to the bind-mounted data/ directory:

• IV.MSSA_<start>-<end>.mseed
• IV.MSSA_<start>-<end>.png

Explicit window instead of an origin:

... seedlink-grab download --host discovery.ms.ingv.it --port 39962 \
    --net IV --sta MSSA --cha HHZ.HHN \
    --start 2026-06-15T12:00:02 --end 2026-06-15T12:00:42

One miniSEED per channel

When you need an explicit start/end window and a separate file for each channel, use download-channels. You pass NET / STA / CHA (required) plus an optional LOC and the time window; the tool splits the SeedLink stream by channel (ObsPy) and writes one file each. --cha accepts multiple channels separated by , or ..

docker run --rm -v "$PWD/data:/data" \
    seedlink-grab download-channels \
    --host discovery.ms.ingv.it --port 39962 \
    --net IV --sta MSSA --cha HHZ,HHN,HHE \
    --start 2026-06-15T12:00:02 --end 2026-06-15T12:00:42

Output (one per channel; MSSA has a blank location, shown as --):

• IV.MSSA.--.HHZ__20260615T120002-20260615T120042.mseed
• IV.MSSA.--.HHN__20260615T120002-20260615T120042.mseed
• IV.MSSA.--.HHE__20260615T120002-20260615T120042.mseed

Omit --loc (or pass --loc --) to match any/blank location code.

Add --format sac to write SAC instead of miniSEED (converted with ObsPy). Since SAC holds a single trace per file, a channel with internal gaps yields one file per contiguous segment (...__part1.sac, ...__part2.sac, ...).

docker run --rm -v "$PWD/data:/data" \
    seedlink-grab download-channels \
    --host discovery.ms.ingv.it --port 39962 \
    --net IV --sta MSSA --cha HHZ,HHN,HHE \
    --start 2026-06-15T12:00:02 --end 2026-06-15T12:00:42 --format sac

download-channels: --host --port --net --sta --cha --loc --start --end --out --format

Buffer extent (oldest data available)

info sends INFO STREAMS and prints, per channel, the oldest (begin_time) and newest (end_time) data still in the SeedLink ring buffer. Useful to know how far back you can request a window before it has rolled out of the buffer.

docker run --rm seedlink-grab info \
    --host discovery.ms.ingv.it --port 39962 --net IV --sta MSSA

Output:

CHANNEL                BEGIN (UTC)            END (UTC)
IV.MSSA.--.HHE         2026/06/14 10:18:46    2026/06/15 14:15:23
IV.MSSA.--.HHN         2026/06/14 10:18:45    2026/06/15 14:15:15
IV.MSSA.--.HHZ         2026/06/14 10:18:39    2026/06/15 14:15:21

oldest data available in buffer: 2026/06/14 10:18:39 UTC

Use --raw to dump the full INFO XML. info: --host --port --net --sta --level --raw

Interactive viewer (port 8080)

docker run --rm -p 8080:8080 -v "$PWD/data:/data" \
    -e ORIGIN=2026-06-15T12:00:12 seedlink-grab serve

Open http://localhost:8080. Pick a file from the dropdown (defaults to the most recent download); drag to box-zoom, scroll to zoom, shift-drag to pan, double-click or "reset zoom" to restore. The red dashed line marks the origin time (ORIGIN). Requires internet in the browser (Plotly is loaded from CDN).

Plot an existing file

docker run --rm -v "$PWD/data:/data" seedlink-grab plot \
    --input /data/IV.MSSA_20260615T120002-120042.mseed \
    --origin 2026-06-15T12:00:12

Options

download: --host --port --net --sta --cha --loc --origin --before --after --start --end --out --name --format --plot plot: --input --out --origin

--format (both download and download-channels): mseed (default) or sac. SAC is converted with ObsPy; one file per channel (and per contiguous segment if gappy).

Env: SEEDLINK_HOST (required if --host is omitted; no default), SEEDLINK_PORT (default 39962).

Author

Valentino Lauciani valentino.lauciani@ingv.it

See AUTHORS.md.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.