station-player 0.1.0__tar.gz

station_player-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.venv/
+venv/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+.DS_Store
+node_modules/
+.svelte-kit/
+web/build/
+dist/
+build/
+*.egg-info/
+.env
+.env.local
+
+# User-dropped iTunes XML exports (large, not repo content)
+from_user/*
+!from_user/README.md
+
+# Generated iTunes XML exports (default disk-export destination)
+out/
+output/
+
+# Playwright
+web/test-results/
+web/playwright-report/
+test-results/
+playwright-report/
+playwright-test.*.db
+playwright-test.*.db-wal
+playwright-test.*.db-shm
+playwright-stations.*/
+
+# Coverage output
+.coverage
+web/coverage/
+
+# Database backups (DESIGN.md §14.18). User-data; never repo content.
+backups/
+.claude/
+
+# §16.15 c1 — MkDocs build output. Source lives in docs/; the
+# rendered HTML/CSS/JS lands in site/ and is published to GH Pages
+# via the docs workflow, never committed to main.
+site/
+# §16.15 c4 — OpenAPI dump consumed by mkdocs-render-swagger-plugin.
+# Regenerated by `make docs-openapi` (chained from docs-build +
+# docs-serve); committing would risk drift between the JSON and
+# the FastAPI app's actual schema.
+docs/reference/openapi.json
+# §16.15 c5 — CLI --help dump consumed by the docs build.
+# Regenerated by `make docs-cli`; same drift logic as openapi.json.
+docs/reference/cli.md

station_player-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Raby Whyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

station_player-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: station-player
+Version: 0.1.0
+Summary: Local music and radio player for station-studio playlists
+Author-email: Raby Whyte <rabywhyte@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025-2026 Raby Whyte
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: itunes,music,player,playlist,radio
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Station Player
+
+A music and radio player for the playlists Station Studio makes, built to
+replace iTunes / Music as the thing that actually plays them.
+
+It plays three kinds of thing:
+
+- **Station Studio playlists**: the iTunes XML files Station Studio
+  exports, plus any library you export from Music / iTunes
+  (File › Library › Export Library). Tracks play in the order the station
+  generated them.
+- **Music folders**: any folder of audio files (mp3, m4a/aac, flac, wav,
+  ogg/opus, aiff). Each folder shows up as its own playlist.
+- **Internet radio**: any stream URL, including `.pls` and `.m3u` links.
+  Rebirth Radio is set up out of the box.
+
+It runs as a small local server on your computer with a browser window as
+the UI. It needs nothing beyond Python 3.11+ and listens only on
+`127.0.0.1`, so nothing is reachable from your network.
+
+## Install and run
+
+You need Python 3.11 or newer and [pipx](https://pipx.pypa.io)
+(macOS: `brew install pipx`; Windows: `py -m pip install --user pipx`,
+then `py -m pipx ensurepath`). No checkout of this repo is needed.
+
+Install the latest release (the exact command is on each
+[Station Player release](https://github.com/raby/station-studio/releases)):
+
+```bash
+pipx install https://github.com/raby/station-studio/releases/download/player-v0.1.0/station_player-0.1.0-py3-none-any.whl
+station-player
+```
+
+Once it's on PyPI, this shorter form works too: `pipx install station-player`.
+Upgrade later with `pipx upgrade station-player` (PyPI) or by running
+`pipx install --force` with a newer release's link.
+
+From a checkout, for development:
+
+```bash
+cd player
+python -m station_player
+```
+
+A browser tab opens at <http://127.0.0.1:8765/>. Useful flags:
+
+```bash
+station-player ~/Music/Albums ~/exports/week-012.xml   # add sources on launch
+station-player --port 9000 --no-browser
+```
+
+## Setting it up
+
+Open **Sources & settings** in the sidebar.
+
+1. **Playlists (iTunes XML).** Add an exported `.xml` file, or a folder of
+   them. On first run Station Player adds Station Studio's exports folder
+   (`~/.station-studio/exports`) automatically when it exists, so every
+   week you export appears without doing anything.
+2. **Music folders.** Add the folder your music lives in. Besides
+   appearing under *Folders*, these files are used to find playlist
+   tracks whose saved location no longer exists (matched by file name).
+3. **Path rewrites.** If the playlists were made on another computer, say
+   a Mac library played back on a PC, rewrite the start of the path:
+   from `/Users/rob/Music/iTunes/iTunes Media` to `D:/Music`.
+
+Tracks whose audio file can't be found are greyed out and skipped.
+Only audio files (mp3, m4a/aac, flac, wav, ogg/opus, aiff, webm) are
+ever played or served, whatever a playlist file points at.
+
+Settings live in `~/.station-player/config.json` (override the folder
+with `$STATION_PLAYER_HOME`).
+
+## Playing
+
+- Double-click a track to play from there, or **▶ Play** for the whole
+  playlist. Shuffle and repeat (all / one) sit next to the transport.
+- Keyboard: Tab into the track list, move with ↑ ↓ (Home / End /
+  Page Up / Page Down), Enter plays. Space plays and pauses; ← and →
+  skip 10 seconds. Keyboard media keys
+  and the OS now-playing panel work through the browser's Media Session
+  support.
+- Pausing a radio station and pressing play again reconnects to the live
+  broadcast instead of resuming from where it stopped.
+
+## A note on Station Studio's example stations
+
+The example pools bundled with Station Studio are synthetic: their tracks
+have no audio files behind them, so they load but show as missing. Point
+Station Studio at an export of your own library and the playlists it
+generates carry each track's file location through to this player.
+
+## Development
+
+```bash
+cd player
+python -m pytest
+```
+
+### Releasing
+
+Bump `version` in `player/pyproject.toml` and merge to main, then run
+**Actions → Publish Station Player → Run workflow**. It tests, builds,
+smoke-installs the wheel and creates a `player-v<version>` GitHub
+release with the files attached. Tick *Also publish to PyPI* to upload
+the same files to pypi.org (one-time setup is described at the top of
+`.github/workflows/publish-player.yml`).
+
+The server is `station_player/server.py` (standard library
+`http.server`), the library reader is `station_player/library.py`, and
+the UI is plain HTML / CSS / JS in `station_player/static/`.

station_player-0.1.0/README.md

@@ -0,0 +1,112 @@
+# Station Player
+
+A music and radio player for the playlists Station Studio makes, built to
+replace iTunes / Music as the thing that actually plays them.
+
+It plays three kinds of thing:
+
+- **Station Studio playlists**: the iTunes XML files Station Studio
+  exports, plus any library you export from Music / iTunes
+  (File › Library › Export Library). Tracks play in the order the station
+  generated them.
+- **Music folders**: any folder of audio files (mp3, m4a/aac, flac, wav,
+  ogg/opus, aiff). Each folder shows up as its own playlist.
+- **Internet radio**: any stream URL, including `.pls` and `.m3u` links.
+  Rebirth Radio is set up out of the box.
+
+It runs as a small local server on your computer with a browser window as
+the UI. It needs nothing beyond Python 3.11+ and listens only on
+`127.0.0.1`, so nothing is reachable from your network.
+
+## Install and run
+
+You need Python 3.11 or newer and [pipx](https://pipx.pypa.io)
+(macOS: `brew install pipx`; Windows: `py -m pip install --user pipx`,
+then `py -m pipx ensurepath`). No checkout of this repo is needed.
+
+Install the latest release (the exact command is on each
+[Station Player release](https://github.com/raby/station-studio/releases)):
+
+```bash
+pipx install https://github.com/raby/station-studio/releases/download/player-v0.1.0/station_player-0.1.0-py3-none-any.whl
+station-player
+```
+
+Once it's on PyPI, this shorter form works too: `pipx install station-player`.
+Upgrade later with `pipx upgrade station-player` (PyPI) or by running
+`pipx install --force` with a newer release's link.
+
+From a checkout, for development:
+
+```bash
+cd player
+python -m station_player
+```
+
+A browser tab opens at <http://127.0.0.1:8765/>. Useful flags:
+
+```bash
+station-player ~/Music/Albums ~/exports/week-012.xml   # add sources on launch
+station-player --port 9000 --no-browser
+```
+
+## Setting it up
+
+Open **Sources & settings** in the sidebar.
+
+1. **Playlists (iTunes XML).** Add an exported `.xml` file, or a folder of
+   them. On first run Station Player adds Station Studio's exports folder
+   (`~/.station-studio/exports`) automatically when it exists, so every
+   week you export appears without doing anything.
+2. **Music folders.** Add the folder your music lives in. Besides
+   appearing under *Folders*, these files are used to find playlist
+   tracks whose saved location no longer exists (matched by file name).
+3. **Path rewrites.** If the playlists were made on another computer, say
+   a Mac library played back on a PC, rewrite the start of the path:
+   from `/Users/rob/Music/iTunes/iTunes Media` to `D:/Music`.
+
+Tracks whose audio file can't be found are greyed out and skipped.
+Only audio files (mp3, m4a/aac, flac, wav, ogg/opus, aiff, webm) are
+ever played or served, whatever a playlist file points at.
+
+Settings live in `~/.station-player/config.json` (override the folder
+with `$STATION_PLAYER_HOME`).
+
+## Playing
+
+- Double-click a track to play from there, or **▶ Play** for the whole
+  playlist. Shuffle and repeat (all / one) sit next to the transport.
+- Keyboard: Tab into the track list, move with ↑ ↓ (Home / End /
+  Page Up / Page Down), Enter plays. Space plays and pauses; ← and →
+  skip 10 seconds. Keyboard media keys
+  and the OS now-playing panel work through the browser's Media Session
+  support.
+- Pausing a radio station and pressing play again reconnects to the live
+  broadcast instead of resuming from where it stopped.
+
+## A note on Station Studio's example stations
+
+The example pools bundled with Station Studio are synthetic: their tracks
+have no audio files behind them, so they load but show as missing. Point
+Station Studio at an export of your own library and the playlists it
+generates carry each track's file location through to this player.
+
+## Development
+
+```bash
+cd player
+python -m pytest
+```
+
+### Releasing
+
+Bump `version` in `player/pyproject.toml` and merge to main, then run
+**Actions → Publish Station Player → Run workflow**. It tests, builds,
+smoke-installs the wheel and creates a `player-v<version>` GitHub
+release with the files attached. Tick *Also publish to PyPI* to upload
+the same files to pypi.org (one-time setup is described at the top of
+`.github/workflows/publish-player.yml`).
+
+The server is `station_player/server.py` (standard library
+`http.server`), the library reader is `station_player/library.py`, and
+the UI is plain HTML / CSS / JS in `station_player/static/`.

station_player-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+# Station Player — a separate app from station-studio that plays its
+# exported iTunes XML playlists, local music folders and radio streams.
+# Standard library only at runtime, so `pipx install ./player` is the
+# whole install.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "station-player"
+version = "0.1.0"
+description = "Local music and radio player for station-studio playlists"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Raby Whyte", email = "rabywhyte@gmail.com" },
+]
+keywords = ["music", "player", "radio", "itunes", "playlist"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+station-player = "station_player.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["station_player"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

station_player-0.1.0/station_player/__init__.py

@@ -0,0 +1,9 @@
+"""Station Player — a local music + radio player for station-studio output.
+
+Plays the iTunes XML playlists station-studio generates (and any iTunes /
+Music library export), plain folders of audio files, and internet radio
+streams. Runs as a small local web server bound to 127.0.0.1 with a
+browser UI; standard library only, no third-party dependencies.
+"""
+
+__version__ = "0.1.0"

station_player-0.1.0/station_player/__main__.py

@@ -0,0 +1,102 @@
+"""`station-player` command: start the local server and open the UI."""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import webbrowser
+from pathlib import Path
+
+from station_player import __version__
+from station_player.config import ConfigStore
+from station_player.library import AUDIO_EXTENSIONS
+from station_player.server import PlayerApp, make_server
+
+
+def _folder_contents(folder: Path) -> tuple[bool, bool]:
+    """(has .xml, has audio) anywhere below folder; stops once both seen."""
+    has_xml = has_audio = False
+    for p in folder.rglob("*"):
+        suffix = p.suffix.lower()
+        if suffix == ".xml":
+            has_xml = True
+        elif suffix in AUDIO_EXTENSIONS:
+            has_audio = True
+        if has_xml and has_audio:
+            break
+    return has_xml, has_audio
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="station-player",
+        description="Play station-studio playlists, local music folders and radio streams.",
+    )
+    parser.add_argument("sources", nargs="*", metavar="PATH",
+                        help="iTunes XML files, folders of XMLs, or folders of audio to add")
+    parser.add_argument("--port", type=int, default=8765, help="port to listen on (default 8765)")
+    parser.add_argument("--no-browser", action="store_true", help="don't open a browser window")
+    parser.add_argument("--version", action="version", version=f"station-player {__version__}")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    store = ConfigStore()
+    added = False
+    for raw in args.sources:
+        p = Path(raw).expanduser().resolve()
+        if not p.exists():
+            print(f"Skipped {raw}: not found", file=sys.stderr)
+            continue
+        if p.is_file():
+            if p.suffix.lower() != ".xml":
+                print(f"Skipped {raw}: pass an iTunes .xml file or a folder", file=sys.stderr)
+                continue
+            targets = [store.config.playlist_sources]
+        else:
+            # Folders holding XML at any depth (station-studio writes
+            # exports/<station>/<week>.xml) are playlist sources; folders
+            # holding audio are music folders. An iTunes folder is both.
+            try:
+                has_xml, has_audio = _folder_contents(p)
+            except OSError as exc:
+                print(f"Skipped {raw}: {exc}", file=sys.stderr)
+                continue
+            targets = []
+            if has_xml:
+                targets.append(store.config.playlist_sources)
+            if has_audio or not has_xml:
+                targets.append(store.config.music_folders)
+        for target in targets:
+            if str(p) not in target:
+                target.append(str(p))
+                added = True
+    if added:
+        try:
+            store.save()
+        except OSError as exc:
+            print(f"Could not save settings to {store.path}: {exc}", file=sys.stderr)
+    app = PlayerApp(store)  # scans once, with every source in place
+
+    try:
+        server = make_server(app, port=args.port)
+    except OSError as exc:
+        print(f"Could not listen on port {args.port}: {exc}", file=sys.stderr)
+        return 1
+    url = f"http://127.0.0.1:{args.port}/"
+    print(f"Station Player {__version__} on {url}  (Ctrl+C to quit)")
+    print(f"Settings: {store.path}")
+    for err in app.library.errors:
+        print(f"  ! {err}")
+    if not args.no_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

station_player-0.1.0/station_player/config.py

@@ -0,0 +1,124 @@
+"""Player settings, stored as JSON under the player's home folder.
+
+Resolution: `$STATION_PLAYER_HOME`, else `~/.station-player/`. The file
+is small and human-editable; the UI writes it through the API.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+ENV_VAR = "STATION_PLAYER_HOME"
+
+DEFAULT_STATIONS = [
+    {
+        "name": "Rebirth Radio",
+        "url": "https://sh.uk.audio-stream.com/proxy/adgerdes?mp=/stream",
+    },
+]
+
+
+def get_home() -> Path:
+    override = os.environ.get(ENV_VAR, "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".station-player"
+
+
+def station_studio_exports() -> Path:
+    """Where station-studio writes exported playlists (its app-home)."""
+    override = os.environ.get("STATION_STUDIO_HOME", "").strip()
+    base = Path(override).expanduser() if override else Path.home() / ".station-studio"
+    return base / "exports"
+
+
+@dataclass
+class Config:
+    # iTunes XML files, or folders that are scanned for *.xml
+    playlist_sources: list[str] = field(default_factory=list)
+    # folders of audio files; each becomes a playlist, and their files
+    # are used to find tracks whose iTunes Location has moved
+    music_folders: list[str] = field(default_factory=list)
+    # [{"from": "/Users/rob/Music", "to": "D:/Music"}]
+    path_remaps: list[dict] = field(default_factory=list)
+    # [{"name": ..., "url": ...}]
+    stations: list[dict] = field(default_factory=lambda: [dict(s) for s in DEFAULT_STATIONS])
+
+    def to_json(self) -> dict:
+        return asdict(self)
+
+
+def _str_list(value) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [v for v in value if isinstance(v, str) and v.strip()]
+
+
+def _pairs(value, keys: tuple[str, str]) -> list[dict]:
+    if not isinstance(value, list):
+        return []
+    return [
+        {k: v[k] for k in keys} for v in value
+        if isinstance(v, dict) and all(isinstance(v.get(k), str) and v[k].strip() for k in keys)
+    ]
+
+
+def config_from_json(data: dict) -> Config:
+    """Build a Config from parsed JSON, dropping anything malformed."""
+    cfg = Config(
+        playlist_sources=_str_list(data.get("playlist_sources")),
+        music_folders=_str_list(data.get("music_folders")),
+        path_remaps=_pairs(data.get("path_remaps"), ("from", "to")),
+    )
+    if "stations" in data:
+        cfg.stations = _pairs(data.get("stations"), ("name", "url"))
+    return cfg
+
+
+class ConfigStore:
+    def __init__(self, home: Path | None = None) -> None:
+        self.home = home or get_home()
+        self.path = self.home / "config.json"
+        self._lock = threading.Lock()
+        self.warnings: list[str] = []
+        self.config = self._read()
+
+    def _read(self) -> Config:
+        if not self.path.is_file():
+            cfg = Config()
+            exports = station_studio_exports()
+            if exports.is_dir():
+                cfg.playlist_sources.append(str(exports.resolve()))
+            return cfg
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                raise ValueError("expected a JSON object")
+        except (OSError, ValueError) as exc:
+            # Keep the broken file for the user to fix rather than
+            # overwriting it with defaults on the next save.
+            backup = self.path.with_name(f"config.broken-{int(time.time())}.json")
+            try:
+                self.path.replace(backup)
+                where = f"moved to {backup}"
+            except OSError:
+                where = f"left at {self.path}"
+            message = f"Settings file could not be read ({exc}); started with defaults, old file {where}"
+            logger.warning(message)
+            self.warnings.append(message)
+            return Config()
+        return config_from_json(data)
+
+    def save(self) -> None:
+        with self._lock:
+            self.home.mkdir(parents=True, exist_ok=True)
+            tmp = self.path.with_suffix(".json.tmp")
+            tmp.write_text(json.dumps(self.config.to_json(), indent=2), encoding="utf-8")
+            tmp.replace(self.path)