Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ audio-streaming library, taking its command-line and control ergonomics from
> The initial task brings up the build and boots a sendspin client; feature work
> is tracked in [`docs/ROADMAP.md`](docs/ROADMAP.md).

**New here?** The [wiki](https://github.com/chrisuthe/sendspin-cpp-cli/wiki) is the
**New here?** The [wiki](https://github.com/Sendspin/sendspin-cpp-cli/wiki) is the
task-shaped version of this file — installing, a Raspberry Pi walkthrough, troubleshooting —
and on Linux [`scripts/get_started_linux.sh`](scripts/get_started_linux.sh) does the install
in one command. Those pages are authored in [`docs/wiki/`](docs/wiki) and mirrored to the
Expand Down Expand Up @@ -77,7 +77,7 @@ CI turns it on, which is where the line is actually held.
> propagates to anything that links it.

```bash
git clone https://github.com/chrisuthe/sendspin-cpp-cli.git
git clone https://github.com/Sendspin/sendspin-cpp-cli.git
cd sendspin-cpp-cli
cmake -B build
cmake --build build
Expand Down
16 changes: 9 additions & 7 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -1208,13 +1208,15 @@ operator to choose between `Type=simple` and `Type=forking` and write the unit t
with nothing in it, because the assertion downstream compares the receipt against the value
that was passed: without the guard, a dropped output would leave both sides equal and empty
and the check would pass on an installer that had lost its version.
- **The receipt is `io.github.chrisuthe.sendspin-cli`.** A namespace this repository actually
owns, rather than an `io.sendspin.*` or Open Home Foundation one it does not — the same
manners the component argument above makes of ArduinoJson. `sendspin-cli` and not
`sendspin-cpp-cli` for the reason the doc directory is named that way: everything anyone
types is the binary's name, and this string is typed, by an operator running
`pkgutil --forget`. Moving the repository under the Sendspin org would change it, and
changing it orphans the receipt of every install before the change rather than upgrading it.
- **The receipt is `io.github.chrisuthe.sendspin-cli`.** A namespace the author holds, rather
than an `io.sendspin.*` or Open Home Foundation one that was not this project's to take when
the identifier was minted — the same manners the component argument above makes of
ArduinoJson. `sendspin-cli` and not `sendspin-cpp-cli` for the reason the doc directory is
named that way: everything anyone types is the binary's name, and this string is typed, by an
operator running `pkgutil --forget`. The repository has since moved under the Sendspin org,
which makes `io.sendspin.*` available to it for the first time, and the identifier
deliberately does not follow: changing it orphans the receipt of every install before the
change rather than upgrading it.
- **The `.pkg` is shipped honestly, and the installer says so itself.** It is unsigned and
unnotarized; `spctl -a -t install` rejects it exactly as `spctl -a -t exec` rejects the
ad-hoc-signed binary inside. The welcome pane carries that, what gets installed, and how to
Expand Down
2 changes: 1 addition & 1 deletion docs/wiki/Configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ shape for a unit whose stderr journald already has. See
[Running as a Service](Running-as-a-Service#what-is-hardened).

The full argument, including why the search does not merge layers, is in
[The config file, and what the player remembers](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-config-file-and-what-the-player-remembers).
[The config file, and what the player remembers](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-config-file-and-what-the-player-remembers).

## The state file

Expand Down
2 changes: 1 addition & 1 deletion docs/wiki/Controlling-the-Player.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Changing it mid-stream re-times chunk scheduling, so expect a brief resync — s
stopped where you can.

The long version of all three is in
[The local control channel](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-local-control-channel).
[The local control channel](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-local-control-channel).

## Reading `status`

Expand Down
6 changes: 3 additions & 3 deletions docs/wiki/Getting-Started-on-Linux.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ page plus the handful of things a Pi does differently.
## The short way

```bash
curl -fLO https://raw.githubusercontent.com/chrisuthe/sendspin-cpp-cli/main/scripts/get_started_linux.sh
curl -fLO https://raw.githubusercontent.com/Sendspin/sendspin-cpp-cli/main/scripts/get_started_linux.sh
less get_started_linux.sh # it is about to run things as root; read it
chmod +x get_started_linux.sh
./get_started_linux.sh
Expand Down Expand Up @@ -116,7 +116,7 @@ output = hw:1,0
```

Three forms are worth knowing, and there are more in
[Choosing an output](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#choosing-an-output):
[Choosing an output](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#choosing-an-output):

| Value | What it means |
|---|---|
Expand Down Expand Up @@ -170,7 +170,7 @@ server = mdns:Music Assistant # or discover one by its advertised name

Any `server` value turns the mDNS advertisement off. That is the spec's rule rather than a
preference here, and the two modes are mutually exclusive by design — see
[The two connection modes](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-two-connection-modes).
[The two connection modes](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-two-connection-modes).

## Next

Expand Down
8 changes: 4 additions & 4 deletions docs/wiki/Getting-Started-on-a-Raspberry-Pi.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ the same `linux-arm64` archive an arm64 server does — plus the five things on

**The builds are `arm64` only. There is no 32-bit ARM build, and none is coming from CI.**
The matrix has no armv7 or 32-bit Pi leg, which is recorded in
[`docs/ROADMAP.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md),
[`docs/ROADMAP.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md),
item 12.

Check what you are running before anything else:
Expand Down Expand Up @@ -47,7 +47,7 @@ wrong.
Exactly as on any Linux host:

```bash
curl -fLO https://raw.githubusercontent.com/chrisuthe/sendspin-cpp-cli/main/scripts/get_started_linux.sh
curl -fLO https://raw.githubusercontent.com/Sendspin/sendspin-cpp-cli/main/scripts/get_started_linux.sh
less get_started_linux.sh # read it before it runs things as root
chmod +x get_started_linux.sh
./get_started_linux.sh
Expand Down Expand Up @@ -126,7 +126,7 @@ nothing for a player running as you.
- **SD cards wear out**, and the state file is rewritten whole on every *distinct* volume a
server sends. A repeat of the current value is skipped, but a slider drag is one rewrite
per step; debouncing is a known gap, listed under
[`docs/ROADMAP.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
[`docs/ROADMAP.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
item 8. If that worries you, point the state at the runtime directory, which is already a
tmpfs — and accept that volume, mute and the static delay are then forgotten across
reboots. It has to be a **drop-in** rather than a config key, because the unit passes
Expand All @@ -146,7 +146,7 @@ nothing for a player running as you.
entirely, and a fixed endpoint deserves a cable.
- **Underruns on a busy Pi** show as clicks or dropouts. Raise the buffer:
`buffer-ms = 250` in the config. The default is 100 ms and the range is 10–2000; see
[Buffering, and what gets advertised](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#buffering-and-what-gets-advertised).
[Buffering, and what gets advertised](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#buffering-and-what-gets-advertised).
- **`avahi-daemon` is what provides mDNS on a Pi**, and Raspberry Pi OS ships it running. If
you have turned it off, the player warns and retries rather than failing — but nothing will
discover it until it is back.
Expand Down
14 changes: 7 additions & 7 deletions docs/wiki/Home.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ player in the group, and takes its flags and its ergonomics from squeezelite so
muscle memory carries over.

> **Status: early scaffold.** The player works; not everything on the roadmap is built.
> [`docs/ROADMAP.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
> [`docs/ROADMAP.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
> is the honest list of what is and is not done.

## Start here
Expand All @@ -35,7 +35,7 @@ That is the whole of the usual setup: nothing to configure on either end. A Send
server discovers the advertisement and dials in. `-s <server>` inverts it and makes this
player the one dialling, which the protocol treats as the other of two mutually exclusive
modes — see
[The two connection modes](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-two-connection-modes).
[The two connection modes](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-two-connection-modes).

Audio goes out through ALSA (the Linux default) or PortAudio (the cross-platform one, and
the only way to make noise on macOS), with volume applied in software on a curve the spec
Expand All @@ -61,19 +61,19 @@ build time, so it turns an Intel Mac away rather than reporting success.

There is no 32-bit ARM build and no Intel-Mac build. The CI matrix has no armv7, 32-bit Pi
or macOS `x86_64` leg, which is recorded in
[`docs/ROADMAP.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md),
[`docs/ROADMAP.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md),
item 12.
Anything else builds from source.

## Where things live

- **[`README.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md)** is
- **[`README.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md)** is
the reference, and ships inside every archive at
`usr/local/share/doc/sendspin-cli/README.md`. It explains *why* the player behaves as it
does — the two connection modes, how `-o` resolves its argument, why `vol` is the group's
volume and not this box's. These wiki pages link into it rather than restating it, so
there is one copy of each argument and it is the copy an offline tarball holder also has.
- **[`docs/ROADMAP.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)**
- **[`docs/ROADMAP.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)**
is what is built, what is not, and what was actually tested rather than reasoned about.
- **`sendspin-cli --help`** is the flag reference, and the config file's reference too:
every config key is a long flag name minus its dashes.
Expand All @@ -83,9 +83,9 @@ Anything else builds from source.
**This wiki is generated. Do not edit it here — the edit will be overwritten.**

The pages are authored in the repository at
[`docs/wiki/`](https://github.com/chrisuthe/sendspin-cpp-cli/tree/main/docs/wiki) and
[`docs/wiki/`](https://github.com/Sendspin/sendspin-cpp-cli/tree/main/docs/wiki) and
mirrored here by
[`.github/workflows/wiki.yml`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/.github/workflows/wiki.yml)
[`.github/workflows/wiki.yml`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/.github/workflows/wiki.yml)
on every push to `main`. A page removed there is removed here; a page changed here is put
back on the next push.

Expand Down
14 changes: 7 additions & 7 deletions docs/wiki/Installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Four ways in, depending on what you have. If you are on Linux and want the short
| Anything else | [Build from source](#build-from-source) |

Everything published is on the
[Releases page](https://github.com/chrisuthe/sendspin-cpp-cli/releases). Per-commit builds
[Releases page](https://github.com/Sendspin/sendspin-cpp-cli/releases). Per-commit builds
of unreleased work are under the repository's Actions tab and expire after 14 days — see
[CI](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#ci).
[CI](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#ci).

> **No release exists yet.** `v0.1.0` has not been tagged at the time of writing, so until
> it is, the only routes are building from source or staging a payload yourself. The
Expand Down Expand Up @@ -46,7 +46,7 @@ nothing. Read `BUILD-INFO.txt` first; it names the runtime packages that build n
# 1. Take the archive for this machine's architecture, and the checksums
VERSION=0.1.0
ARCH=$(uname -m); [ "$ARCH" = aarch64 ] && LEG=linux-arm64 || LEG=linux-x86_64
BASE=https://github.com/chrisuthe/sendspin-cpp-cli/releases/download/v$VERSION
BASE=https://github.com/Sendspin/sendspin-cpp-cli/releases/download/v$VERSION
curl -fLO "$BASE/sendspin-cli-$VERSION-$LEG.tar.gz"
curl -fLO "$BASE/SHA256SUMS"

Expand Down Expand Up @@ -123,9 +123,9 @@ xattr -d com.apple.quarantine ./sendspin-cli-0.1.0-macos-arm64/usr/local/bin/sen

The full picture — including why `sudo installer` is not gated at all, and why the `.pkg`
exists despite not fixing Gatekeeper — is in
[macOS, and Gatekeeper](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#macos-and-gatekeeper)
[macOS, and Gatekeeper](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#macos-and-gatekeeper)
and
[The macOS installer `.pkg`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-macos-installer-pkg).
[The macOS installer `.pkg`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-macos-installer-pkg).
A Developer ID signature and notarization are owed and tracked as roadmap item 10.

There is no launchd job in the payload. On macOS the player runs from a shell or under a
Expand All @@ -147,7 +147,7 @@ sudo apt install pkg-config libasound2-dev portaudio19-dev libavahi-compat-libdn
sudo dnf install pkgconf alsa-lib-devel portaudio-devel avahi-compat-libdns_sd-devel # Fedora / RHEL
brew install portaudio pkgconf # macOS

git clone https://github.com/chrisuthe/sendspin-cpp-cli.git
git clone https://github.com/Sendspin/sendspin-cpp-cli.git
cd sendspin-cpp-cli
cmake -B build
cmake --build build
Expand Down Expand Up @@ -179,7 +179,7 @@ sudo cmake --install build --component sendspin-cli
files belonging to a fetched dependency. The prefix is fixed at *configure* time because
the unit's `ExecStart` names it absolutely, so reconfigure rather than passing
`--install --prefix`. Both points, at length, in
[Install](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#install).
[Install](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#install).

## Next

Expand Down
8 changes: 4 additions & 4 deletions docs/wiki/Running-as-a-Service.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ the unit runs as, out of a declaration installed beside the unit, and a tarball
> session for ALSA's `default` PCM to follow. Run `sendspin-cli -l`, pick a card, and put
> `output = hw:1,0` in `/etc/sendspin-cli.conf`.
> [Getting Started on Linux](Getting-Started-on-Linux) has the argument in full, and is why
> [`scripts/get_started_linux.sh`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/scripts/get_started_linux.sh)
> [`scripts/get_started_linux.sh`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/scripts/get_started_linux.sh)
> enables this unit without starting it.

## What the payload installs
Expand Down Expand Up @@ -177,11 +177,11 @@ Read the installed unit for the full block. Three operator-visible edges:
- Four directives that would gate what the ALSA backend reaches are deliberately *absent* —
`PrivateDevices=`, `DeviceAllow=`, `ProcSubset=pid` and `RestrictRealtime=` — because they
pass every check a machine with no sound card can make, and tracked as
[`docs/ROADMAP.md`](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
[`docs/ROADMAP.md`](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
item 10.

The full argument for every directive, and the `systemd-analyze security` figures, are in
[The systemd unit](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-systemd-unit).
[The systemd unit](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-systemd-unit).

### Changing any of it

Expand Down Expand Up @@ -225,7 +225,7 @@ saying why".

Lines are not timestamped by the player under systemd, because journald already stamps them
and a second one would be noise. Only a `-f` logfile gets our own timestamp. See
[Logging](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#logging).
[Logging](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#logging).

## A user unit instead

Expand Down
8 changes: 4 additions & 4 deletions docs/wiki/Troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ and the Sendspin spec forbids advertising while it is
```

There is deliberately no flag that turns both modes on together. See
[The two connection modes](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#the-two-connection-modes).
[The two connection modes](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#the-two-connection-modes).

**`no-mdns` is set.** Remove it.

Expand Down Expand Up @@ -300,7 +300,7 @@ buffer-ms = 250
That is one figure for every backend — ALSA divides it into periods, PortAudio makes it the
ring size, and a device-less sink ignores it. A figure smaller than one device buffer is
raised to the floor and says so at `debug`. See
[Buffering, and what gets advertised](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#buffering-and-what-gets-advertised).
[Buffering, and what gets advertised](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#buffering-and-what-gets-advertised).

If it is one speaker out of sync with the others rather than dropping out, that is
`delay`, not `buffer-ms` — see [Controlling the Player](Controlling-the-Player).
Expand Down Expand Up @@ -332,12 +332,12 @@ sendspin-cli -z -f /var/log/sendspin-cli.log -P /run/sendspin-cli.pid

Under systemd, neither flag belongs: `Type=simple` in the foreground puts everything in the
journal. See
[Running as a daemon](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md#running-as-a-daemon).
[Running as a daemon](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md#running-as-a-daemon).

## Still stuck

Collect this and open an issue at
[the repository](https://github.com/chrisuthe/sendspin-cpp-cli/issues):
[the repository](https://github.com/Sendspin/sendspin-cpp-cli/issues):

```bash
sendspin-cli --version
Expand Down
8 changes: 4 additions & 4 deletions docs/wiki/_Sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@

---

- [Repository](https://github.com/chrisuthe/sendspin-cpp-cli)
- [README](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/README.md)
- [Roadmap](https://github.com/chrisuthe/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
- [Releases](https://github.com/chrisuthe/sendspin-cpp-cli/releases)
- [Repository](https://github.com/Sendspin/sendspin-cpp-cli)
- [README](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/README.md)
- [Roadmap](https://github.com/Sendspin/sendspin-cpp-cli/blob/main/docs/ROADMAP.md)
- [Releases](https://github.com/Sendspin/sendspin-cpp-cli/releases)
2 changes: 1 addition & 1 deletion packaging/sendspin-cli.service.in
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@

[Unit]
Description=Sendspin audio player
Documentation=https://github.com/chrisuthe/sendspin-cpp-cli
Documentation=https://github.com/Sendspin/sendspin-cpp-cli
# network.target rather than network-online.target: the player retries its mDNS advertisement
# and an -s dial on a backoff, so it comes up perfectly well ahead of the network -- and
# network-online.target delays every boot to buy nothing here. sound.target is ordering only
Expand Down
2 changes: 1 addition & 1 deletion scripts/get_started_linux.sh
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ set -euo pipefail
# The repository releases are taken from. A constant rather than an environment knob: a
# get-started script that can be pointed at any repository is a get-started script that can
# be pointed at somebody else's binary.
readonly REPO='chrisuthe/sendspin-cpp-cli'
readonly REPO='Sendspin/sendspin-cpp-cli'

readonly UNIT='sendspin-cli'
readonly UNIT_FILE='/usr/local/lib/systemd/system/sendspin-cli.service'
Expand Down
Loading