streamflacr 0.1.0__py3-none-any.whl

streamflacr/__init__.py

@@ -0,0 +1,2 @@
+"""StreamFLACr - Auto-download FLAC from Soulseek for SoundCloud playlist additions."""
+__version__ = "0.1.0"

streamflacr/__main__.py

@@ -0,0 +1,200 @@
+"""StreamFLACr main daemon.
+
+Monitors ALL SoundCloud playlists for the authenticated user, searches
+Soulseek for FLAC versions of new tracks, downloads them, tags metadata,
+and creates matching Serato smart crates.
+"""
+
+import asyncio
+import logging
+from pathlib import Path
+
+from .config import (
+    DOWNLOAD_DIR,
+    SEARCH_TIMEOUT,
+    SOUNDCLOUD_POLL_INTERVAL,
+    SOUNDCLOUD_USER_URL,
+)
+from .metadata import tag_flac
+from .notify import send_notification
+from .serato_crate import ensure_smart_crate
+from .soundcloud import (
+    PlaylistInfo,
+    TrackInfo,
+    discover_user_playlists,
+    fetch_playlist_tracks,
+    refresh_playlist_tracks,
+    _api_get,
+)
+from .soulseek import SoulseekDownloader
+from .state import StateManager
+
+logger = logging.getLogger("streamflacr")
+
+
+async def process_new_track(
+    track: TrackInfo,
+    playlist_name: str,
+    slsk: SoulseekDownloader,
+    state: StateManager,
+    playlist_url: str,
+) -> Path | None:
+    """Search, download, tag, and integrate a single track. Returns local path on success."""
+    logger.info("Processing: %s - %s", track.artist, track.title)
+
+    candidates = await slsk.search_flac(track.artist, track.title, timeout=SEARCH_TIMEOUT)
+    if not candidates:
+        logger.warning("No FLAC found on Soulseek for: %s - %s", track.artist, track.title)
+        send_notification("StreamFLACr", f"No FLAC found: {track.artist} - {track.title}")
+        return None
+
+    for candidate in candidates[:3]:
+        local_path = await slsk.download(candidate["username"], candidate["remote_path"])
+        if local_path and local_path.exists():
+            tag_flac(
+                filepath=local_path,
+                artist=track.artist,
+                title=track.title,
+                playlist_name=playlist_name,
+            )
+            state.mark_downloaded(
+                playlist_url=playlist_url,
+                track_id=track.track_id,
+                artist=track.artist,
+                title=track.title,
+                local_path=str(local_path),
+            )
+            send_notification("StreamFLACr", f"Downloaded: {track.artist} - {track.title}")
+            return local_path
+
+    logger.error("All download attempts failed for: %s - %s", track.artist, track.title)
+    send_notification("StreamFLACr", f"Download failed: {track.artist} - {track.title}")
+    return None
+
+
+async def sync_playlist(
+    playlist: PlaylistInfo,
+    slsk: SoulseekDownloader,
+    state: StateManager,
+) -> None:
+    """Check a single playlist for new tracks and download FLAC for them."""
+    playlist_url = playlist.url
+    playlist_name = playlist.title
+
+    # Ensure there's a smart crate for this playlist
+    ensure_smart_crate(playlist_name)
+
+    # Fetch current tracks
+    tracks = fetch_playlist_tracks(playlist_url)
+    if not tracks:
+        logger.debug("No tracks found in playlist: %s", playlist_name)
+        return
+
+    current_ids = {t.track_id for t in tracks}
+    seen_ids = state.get_seen_ids(playlist_url)
+    new_ids = current_ids - seen_ids
+
+    if not new_ids:
+        return
+
+    logger.info("Found %d new track(s) in '%s'", len(new_ids), playlist_name)
+    new_tracks = [t for t in tracks if t.track_id in new_ids]
+
+    for track in new_tracks:
+        try:
+            await process_new_track(track, playlist_name, slsk, state, playlist_url)
+        except Exception as e:
+            logger.error("Error processing track %s: %s", track.title, e)
+
+    # Mark all new tracks as seen (even failed ones)
+    state.mark_seen(playlist_url, list(new_ids))
+    state.save()
+
+
+async def poll_loop(slsk: SoulseekDownloader, state: StateManager) -> None:
+    """Main polling loop: discover all playlists, check each for new tracks."""
+    # Initial sync: discover all existing playlists and mark their tracks as seen
+    existing_playlists = discover_user_playlists(
+        f"{SOUNDCLOUD_USER_URL}/sets" if SOUNDCLOUD_USER_URL else None
+    )
+
+    for playlist in existing_playlists:
+        tracks = fetch_playlist_tracks(playlist.url)
+        playlist.tracks = tracks
+        state.set_playlist_name(playlist.url, playlist.title)
+        state.mark_seen(playlist.url, [t.track_id for t in tracks])
+        # Create smart crate for each existing playlist
+        ensure_smart_crate(playlist.title)
+    state.save()
+
+    total_tracks = sum(len(p.tracks) for p in existing_playlists)
+    logger.info(
+        "Initial sync: %d playlists, %d tracks already known",
+        len(existing_playlists),
+        total_tracks,
+    )
+    send_notification("StreamFLACr", f"Watching {len(existing_playlists)} playlists")
+
+    known_playlist_urls = {p.url for p in existing_playlists}
+
+    while True:
+        await asyncio.sleep(SOUNDCLOUD_POLL_INTERVAL)
+
+        try:
+            # Re-discover playlists to catch newly created ones
+            current_playlists = discover_user_playlists(
+                f"{SOUNDCLOUD_USER_URL}/sets" if SOUNDCLOUD_USER_URL else None
+            )
+        except Exception as e:
+            logger.error("Error discovering playlists: %s", e)
+            continue
+
+        # Check for newly created playlists
+        for playlist in current_playlists:
+            if playlist.url not in known_playlist_urls:
+                logger.info("New playlist detected: '%s'", playlist.title)
+                state.set_playlist_name(playlist.url, playlist.title)
+                ensure_smart_crate(playlist.title)
+                known_playlist_urls.add(playlist.url)
+
+        # Sync each playlist
+        for playlist in current_playlists:
+            try:
+                await sync_playlist(playlist, slsk, state)
+            except Exception as e:
+                logger.error("Error syncing playlist '%s': %s", playlist.title, e)
+
+
+async def run_once(slsk: SoulseekDownloader, state: StateManager) -> None:
+    """Single-pass mode: check all playlists for new tracks, then exit."""
+    playlists = discover_user_playlists(
+        f"{SOUNDCLOUD_USER_URL}/sets" if SOUNDCLOUD_USER_URL else None
+    )
+
+    for playlist in playlists:
+        try:
+            await sync_playlist(playlist, slsk, state)
+        except Exception as e:
+            logger.error("Error syncing playlist '%s': %s", playlist.title, e)
+
+
+async def amain(daemon: bool = False) -> None:
+    DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+    state = StateManager()
+    slsk = SoulseekDownloader()
+
+    try:
+        await slsk.connect()
+
+        if daemon:
+            await poll_loop(slsk, state)
+        else:
+            await run_once(slsk, state)
+    finally:
+        await slsk.disconnect()
+
+
+if __name__ == "__main__":
+    from .cli import main
+    main()

streamflacr/cli.py

@@ -0,0 +1,62 @@
+"""CLI entry point for StreamFLACr."""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from .setup import run_setup, register_launchdaemon, unregister_launchdaemon
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="streamflacr",
+        description="StreamFLACr - Auto-download FLAC from Soulseek for SoundCloud playlist additions",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Default run command (no subcommand)
+    parser.add_argument("-d", "--daemon", action="store_true", help="Run as persistent daemon (poll loop)")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Debug logging")
+
+    # setup subcommand
+    setup_parser = subparsers.add_parser("setup", help="Run interactive setup wizard")
+    setup_parser.add_argument("--uninstall", action="store_true", help="Unregister LaunchDaemon and remove config")
+
+    args = parser.parse_args()
+
+    if args.command == "setup":
+        if args.uninstall:
+            unregister_launchdaemon()
+            return
+        run_setup()
+        return
+
+    # Run the main daemon
+    level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    from .config import SLSK_USERNAME, SLSK_PASSWORD, SOUNDCLOUD_USER_URL
+    missing = []
+    if not SLSK_USERNAME or not SLSK_PASSWORD:
+        missing.append("Soulseek credentials")
+    if not SOUNDCLOUD_USER_URL:
+        missing.append("SoundCloud user URL")
+
+    if missing:
+        logger = logging.getLogger("streamflacr")
+        for m in missing:
+            logger.error("Missing configuration: %s", m)
+        print("\n  Run `streamflacr setup` to configure StreamFLACr.\n")
+        sys.exit(1)
+
+    from .__main__ import amain
+    asyncio.run(amain(daemon=args.daemon))
+
+
+if __name__ == "__main__":
+    main()

streamflacr/config.py

@@ -0,0 +1,29 @@
+"""Configuration management via environment / .env file."""
+
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Soulseek credentials
+SLSK_USERNAME: str = os.environ.get("SLSK_USERNAME", "")
+SLSK_PASSWORD: str = os.environ.get("SLSK_PASSWORD", "")
+
+# SoundCloud
+SOUNDCLOUD_USER_URL: str = os.environ.get("SOUNDCLOUD_USER_URL", "")
+SOUNDCLOUD_POLL_INTERVAL: int = int(os.environ.get("SOUNDCLOUD_POLL_INTERVAL", "300"))  # seconds
+
+# Download destination
+DOWNLOAD_DIR: Path = Path(os.environ.get("DOWNLOAD_DIR", "/Users/djtchill/Music/_Serato_/Auto Import"))
+
+# Serato
+SERATO_DIR: Path = Path(os.environ.get("SERATO_DIR", "/Users/djtchill/Music/_Serato_"))
+
+# State file (tracks last-seen set to avoid re-downloading)
+STATE_FILE: Path = Path(os.environ.get("STATE_FILE", str(Path(__file__).parent.parent / "state.json")))
+
+# Search preferences
+SEARCH_TIMEOUT: int = int(os.environ.get("SEARCH_TIMEOUT", "30"))
+PREFER_FREE_SLOTS: bool = os.environ.get("PREFER_FREE_SLOTS", "1") == "1"
+MIN_FILESIZE_MB: int = int(os.environ.get("MIN_FILESIZE_MB", "5"))

streamflacr/metadata.py

@@ -0,0 +1,43 @@
+"""FLAC metadata tagging via mutagen.
+
+Writes artist, title, album, label (set to the SoundCloud playlist name),
+and other standard Vorbis comment fields.
+"""
+
+import logging
+from pathlib import Path
+
+from mutagen.flac import FLAC
+
+logger = logging.getLogger(__name__)
+
+
+def tag_flac(
+    filepath: Path,
+    artist: str,
+    title: str,
+    playlist_name: str,
+    album: str | None = None,
+    genre: str | None = None,
+    year: str | None = None,
+) -> None:
+    """Write metadata to a FLAC file.
+
+    The 'label' field (Vorbis comment LABEL / publisher) is set to the
+    SoundCloud playlist name so Serato smart crates can match on it.
+    """
+    audio = FLAC(str(filepath))
+
+    audio["artist"] = artist
+    audio["title"] = title
+    audio["label"] = playlist_name  # This is the key Serato field
+
+    if album:
+        audio["album"] = album
+    if genre:
+        audio["genre"] = genre
+    if year:
+        audio["date"] = year
+
+    audio.save()
+    logger.info("Tagged %s: artist=%s, title=%s, label=%s", filepath.name, artist, title, playlist_name)

streamflacr/notify.py

@@ -0,0 +1,18 @@
+"""macOS notification support."""
+
+import logging
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+def send_notification(title: str, message: str) -> None:
+    """Send a macOS notification via osascript."""
+    # Escape for AppleScript
+    title_escaped = title.replace('"', '\\"').replace("\\", "\\\\")
+    message_escaped = message.replace('"', '\\"').replace("\\", "\\\\")
+    script = f'display notification "{message_escaped}" with title "{title_escaped}"'
+    try:
+        subprocess.run(["osascript", "-e", script], check=True, capture_output=True, timeout=5)
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError) as e:
+        logger.warning("Could not send notification: %s", e)

streamflacr/serato_crate.py

@@ -0,0 +1,63 @@
+"""Serato smart crate management via serato-tools.
+
+Creates a smart crate per SoundCloud playlist with a rule:
+    Label IS <playlist_name>
+so that all downloaded FLACs with that label tag auto-populate the crate.
+"""
+
+import logging
+from pathlib import Path
+
+from .config import SERATO_DIR
+
+logger = logging.getLogger(__name__)
+
+
+def _import_serato_tools():
+    """Lazy import serato-tools. Raises ImportError if not installed."""
+    from serato_tools.smart_crate import SmartCrate  # noqa: F401
+    return SmartCrate
+
+
+def ensure_smart_crate(playlist_name: str) -> Path | None:
+    """Create or update a Serato smart crate that matches on Label IS playlist_name.
+
+    Returns the path to the .scrate file, or None if serato-tools is not installed.
+    """
+    try:
+        SmartCrate = _import_serato_tools()
+    except ImportError:
+        logger.warning("serato-tools not installed; skipping smart crate creation")
+        logger.warning("Install with: pip install serato-tools --no-deps")
+        return None
+
+    safe_name = playlist_name.replace("/", "≫").replace("\\", "≫")
+    smart_crates_dir = SERATO_DIR / "SmartCrates"
+    smart_crates_dir.mkdir(parents=True, exist_ok=True)
+    scrate_path = smart_crates_dir / f"{safe_name}.scrate"
+
+    if scrate_path.exists():
+        logger.info("Smart crate already exists: %s", scrate_path.name)
+        sc = SmartCrate(str(scrate_path))
+        _ensure_label_rule(sc, playlist_name)
+        sc.save()
+        return scrate_path
+
+    sc = SmartCrate(str(scrate_path))
+    _ensure_label_rule(sc, playlist_name)
+
+    # Enable live update so Serato refreshes automatically
+    for i, (f, v) in enumerate(sc.entries):
+        if f == SmartCrate.Fields.SMARTCRATE_LIVE_UPDATE:
+            sc.entries[i] = (f, [("brut", True)])
+        if f == SmartCrate.Fields.SMARTCRATE_MATCH_ALL:
+            sc.entries[i] = (f, [("brut", True)])
+
+    sc.save()
+    logger.info("Created smart crate: %s (Label IS '%s')", scrate_path.name, playlist_name)
+    return scrate_path
+
+
+def _ensure_label_rule(sc, playlist_name: str) -> None:
+    """Make sure the smart crate has a Label IS rule for the playlist name."""
+    sc.set_rule(sc.RuleField.LABEL, sc.RuleComparison.STR_IS, playlist_name)