flowmusic-cli 0.1.0__py3-none-any.whl

flowmusic_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Unofficial CLI for Google Flow Music (flowmusic.app)."""
+
+__version__ = "0.1.0"

flowmusic_cli/__main__.py

@@ -0,0 +1,4 @@
+from flowmusic_cli.cli import main
+
+if __name__ == "__main__":
+    main()

flowmusic_cli/api/client.py

@@ -0,0 +1,328 @@
+"""HTTP client for flowmusic.app's backend (reached through the site's ``/__api`` proxy)."""
+
+from __future__ import annotations
+
+import mimetypes
+import time
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from flowmusic_cli.api.sse import SSEEvent, parse_sse
+from flowmusic_cli.auth.session import SessionStore
+from flowmusic_cli.auth.supabase import TokenManager
+from flowmusic_cli.config import DEFAULT_MODEL, Settings
+from flowmusic_cli.errors import (
+    ApiError,
+    AuthExpired,
+    Blocked,
+    FmusicError,
+    NetworkError,
+    NoAccess,
+    OutOfCredits,
+    RateLimited,
+    ServerError,
+)
+
+UPLOAD_AUDIO_INSTRUCTIONS = (
+    "Tool indicating that the user has uploaded an audio file.\n\n"
+    "NOTE: The agent does not have access to this tool directly."
+)
+
+
+def _detail(r: httpx.Response) -> str:
+    try:
+        body = r.json()
+    except ValueError:
+        return (r.text or r.reason_phrase or "")[:300]
+    if isinstance(body, dict):
+        d = body.get("detail") or body.get("error") or body.get("message") or body
+        if isinstance(d, (dict, list)):
+            return str(d)[:300]
+        return str(d)
+    return str(body)[:300]
+
+
+def raise_for_response(r: httpx.Response) -> None:
+    if r.status_code < 400:
+        return
+    detail = _detail(r)
+    low = detail.lower()
+    s = r.status_code
+    if s == 401:
+        raise AuthExpired(detail, status=s)
+    if s == 402 or "credit" in low or "insufficient" in low:
+        raise OutOfCredits(detail, status=s)
+    if s == 403:
+        raise NoAccess(detail, status=s)
+    if s == 429:
+        raise RateLimited(detail, status=s)
+    if s == 451 or "moderat" in low or "policy" in low or "flagged" in low:
+        raise Blocked(detail, status=s)
+    if s >= 500:
+        raise ServerError(f"HTTP {s}: {detail}", status=s)
+    raise ApiError(f"HTTP {s}: {detail}", status=s)
+
+
+class FlowMusicClient:
+    def __init__(
+        self,
+        settings: Settings,
+        profile: str | None = None,
+        *,
+        http: httpx.Client | None = None,
+        max_retries: int = 3,
+    ):
+        self.settings = settings
+        self.store = SessionStore(settings.profile_dir(profile))
+        self.http = http or httpx.Client(
+            timeout=httpx.Timeout(settings.timeout, connect=20),
+            headers={
+                "User-Agent": settings.user_agent,
+                "Accept": "application/json",
+                "Origin": settings.site_url,
+                "Referer": settings.site_url + "/",
+            },
+            follow_redirects=False,
+        )
+        self.tokens = TokenManager(settings, self.store, self.http)
+        self.max_retries = max_retries
+
+    # ------------------------------------------------------------------ core
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> FlowMusicClient:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def _url(self, path: str) -> str:
+        return self.settings.api_base + "/" + path.lstrip("/")
+
+    def _send(self, method: str, path: str, *, stream: bool = False, **kw) -> httpx.Response:
+        """Send with auth, one forced refresh on 401, and backoff on 429/5xx/network errors."""
+        refreshed = False
+        attempt = 0
+        while True:
+            headers = dict(kw.pop("headers", None) or {})
+            headers["Authorization"] = f"Bearer {self.tokens.access_token()}"
+            try:
+                req = self.http.build_request(method, self._url(path), headers=headers, **kw)
+                r = self.http.send(req, stream=stream)
+            except httpx.TimeoutException as e:
+                err: FmusicError = NetworkError(f"Timed out talking to flowmusic.app ({e.__class__.__name__}).")
+                r = None
+            except httpx.HTTPError as e:
+                err = NetworkError(str(e) or e.__class__.__name__)
+                r = None
+            if r is not None:
+                if r.status_code == 401 and not refreshed:
+                    r.close()
+                    refreshed = True
+                    self.tokens.access_token(force_refresh=True)
+                    kw["headers"] = headers
+                    continue
+                if r.status_code < 400:
+                    return r
+                if stream:
+                    r.read()
+                try:
+                    raise_for_response(r)
+                except FmusicError as e:
+                    err = e
+            if not err.retryable or attempt >= self.max_retries:
+                raise err
+            delay = min(2 ** attempt * 2, 30)
+            if r is not None and r.headers.get("Retry-After", "").isdigit():
+                delay = min(int(r.headers["Retry-After"]), 60)
+            time.sleep(delay)
+            attempt += 1
+            kw["headers"] = headers
+
+    def request(self, method: str, path: str, **kw) -> Any:
+        r = self._send(method, path, **kw)
+        if not r.content:
+            return None
+        ctype = r.headers.get("content-type", "")
+        return r.json() if "json" in ctype else r.text
+
+    def get(self, path: str, **params) -> Any:
+        return self.request("GET", path, params={k: v for k, v in params.items() if v is not None})
+
+    def post(self, path: str, body: Any = None, **kw) -> Any:
+        return self.request("POST", path, json=body, **kw)
+
+    # -------------------------------------------------------------- account
+    def me(self) -> dict:
+        return self.get("/users/me")
+
+    def subscription(self) -> dict:
+        return self.get("/subscription")
+
+    def credits(self) -> dict:
+        return self.get("/billing/credits")
+
+    def models(self) -> list[dict]:
+        return (self.get("/models") or {}).get("models", [])
+
+    def access_granted(self) -> dict:
+        return self.get("/producer/access-granted")
+
+    # -------------------------------------------------------- conversations
+    def client_context(self, model: str = DEFAULT_MODEL) -> dict:
+        return {
+            "song_queue": [],
+            "selected_model": model,
+            "lyrics_id_map": {},
+            "ghostwriter_version": "standard",
+            "onboarding_variant": None,
+            "client_platform": "web",
+            "clarifying_questions": {
+                "supports_question_options": False,
+                "supports_multi_question_options": False,
+                "arm": "questionnaire",
+            },
+        }
+
+    def send_message(
+        self,
+        parts: list[dict],
+        *,
+        conversation_id: str | None = None,
+        model: str = DEFAULT_MODEL,
+        mode: str = "standard",
+    ) -> str:
+        body: dict[str, Any] = {
+            "parts": parts,
+            "client_context": self.client_context(model),
+            "model_name": f"producer:{mode}",
+            "mode": mode,
+        }
+        if conversation_id:
+            body["conversation_id"] = conversation_id
+        return self.post("/conversation", body)["job_id"]
+
+    def send_tool_call(
+        self,
+        tool_name: str,
+        args: dict,
+        *,
+        conversation_id: str | None = None,
+        model: str = DEFAULT_MODEL,
+    ) -> str:
+        body = {
+            "conversation_id": conversation_id,
+            "part": {
+                "tool_name": tool_name,
+                "args": args,
+                "tool_call_id": str(uuid.uuid4()),
+                "part_kind": "tool-call",
+            },
+            "client_context": {"ghostwriter_version": "standard", "selected_model": model},
+        }
+        return self.post("/producer/tool-call", body)["job_id"]
+
+    @contextmanager
+    def _stream(self, job_id: str, last_id: str) -> Iterator[httpx.Response]:
+        r = self._send(
+            "GET",
+            f"/messages/{job_id}/stream",
+            params={"last_id": last_id, "tool_progress": "true"},
+            headers={"Accept": "text/event-stream"},
+            timeout=httpx.Timeout(self.settings.timeout, read=120),
+            stream=True,
+        )
+        try:
+            yield r
+        finally:
+            r.close()
+
+    def stream_job(self, job_id: str, *, max_reconnects: int = 5) -> Iterator[SSEEvent]:
+        """Yield SSE events for a job, transparently resuming with ``last_id`` on drops."""
+        last_id = "0"
+        reconnects = 0
+        while True:
+            try:
+                with self._stream(job_id, last_id) as r:
+                    for ev in parse_sse(r.iter_lines()):
+                        if ev.id:
+                            last_id = ev.id
+                        yield ev
+                        if ev.event == "final":
+                            return
+                return  # server closed the stream cleanly
+            except (httpx.HTTPError, NetworkError) as e:
+                reconnects += 1
+                if reconnects > max_reconnects:
+                    raise NetworkError(f"Lost the generation stream: {e}") from e
+                time.sleep(min(2 * reconnects, 10))
+
+    def list_conversations(self, limit: int = 20, offset: int = 0) -> list[dict]:
+        return self.get("/conversations", limit=limit, offset=offset) or []
+
+    def get_conversation(self, conversation_id: str) -> dict:
+        return self.get(f"/conversations/{conversation_id}")
+
+    def running_job(self, conversation_id: str) -> dict:
+        return self.get(f"/conversations/{conversation_id}/running-job")
+
+    def stop_conversation(self, conversation_id: str) -> Any:
+        return self.post(f"/conversations/{conversation_id}/stop")
+
+    # ----------------------------------------------------------------- clips
+    def song_status(self, operation_id: str) -> dict:
+        return self.get(f"/audio-create-song-status/{operation_id}")
+
+    def get_clips(self, clip_ids: list[str]) -> dict[str, dict]:
+        if not clip_ids:
+            return {}
+        return (self.post("/clips", {"clip_ids": list(clip_ids)}) or {}).get("clips", {})
+
+    def get_clip(self, clip_id: str) -> dict:
+        clip = self.get_clips([clip_id]).get(clip_id)
+        # Deleted clips come back as an empty stub ({"id": ...}, everything else null).
+        if not clip or clip.get("deleted_at") or not clip.get("created_at"):
+            raise ApiError(f"Clip {clip_id} not found.", status=404)
+        return clip
+
+    def my_clips(self, limit: int = 20, offset: int = 0) -> list[dict]:
+        return (self.get("/clips/auth-user", limit=limit, offset=offset) or {}).get("clips", [])
+
+    def delete_clips(self, clip_ids: list[str]) -> Any:
+        return self.post("/clips/delete", {"clip_ids": list(clip_ids)})
+
+    def update_clip(self, clip_id: str, **fields) -> Any:
+        return self.request("PATCH", f"/clips/{clip_id}", json=fields)
+
+    def stems(self, clip_id: str) -> dict[str, str]:
+        """Split (on first call) and return ``{stem_name: base64_audio}``."""
+        r = self._send("GET", f"/stems/clip/{clip_id}", timeout=httpx.Timeout(600, connect=20))
+        return (r.json() or {}).get("stems", {})
+
+    # ---------------------------------------------------------------- upload
+    def upload_audio(self, path: Path) -> dict:
+        mime = mimetypes.guess_type(path.name)[0] or "audio/mpeg"
+        content = path.read_bytes()  # site limit is 40 MB; bytes make retries safe
+        r = self._send(
+            "POST",
+            "/producer/upload-audio",
+            files={"file": (path.name, content, mime)},
+            data={"file_type": mime, "filename": path.name},
+            timeout=httpx.Timeout(300, connect=20),
+        )
+        return r.json()
+
+    def upload_check_status(self, clip_id: str, operation_id: str) -> dict:
+        return self.get(f"/producer/upload-audio/{clip_id}/upload-check-status", operation_id=operation_id)
+
+    def confirm_upload(self, clip_id: str, operation_id: str) -> dict:
+        return self.post(f"/producer/upload-audio/{clip_id}/confirm", {"operation_id": operation_id})
+
+    def remove_vocals(self, clip_id: str, operation_id: str) -> dict:
+        return self.post(f"/producer/upload-audio/{clip_id}/remove-vocals", {"operation_id": operation_id})

flowmusic_cli/api/download.py

@@ -0,0 +1,136 @@
+"""Download clip audio/cover and write a metadata sidecar."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+import unicodedata
+from datetime import date
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+
+from flowmusic_cli.errors import ApiError, NetworkError
+
+ALLOWED_HOSTS = ("storage.googleapis.com", "flowmusic.app", "www.flowmusic.app")
+FORMATS = {"wav": "wav_url", "m4a": "audio_url"}
+
+
+def slugify(text: str | None, fallback: str = "untitled") -> str:
+    text = unicodedata.normalize("NFKD", text or "").encode("ascii", "ignore").decode()
+    text = re.sub(r"[^\w\s-]", "", text).strip().lower()
+    text = re.sub(r"[-\s]+", "-", text)
+    return text[:60] or fallback
+
+
+def clip_basename(clip: dict) -> str:
+    return f"{slugify(clip.get('title'))}_{clip['id'][:8]}"
+
+
+def _check_url(url: str) -> None:
+    host = urlparse(url).hostname or ""
+    if urlparse(url).scheme != "https" or not any(host == h or host.endswith("." + h) for h in ALLOWED_HOSTS):
+        raise ApiError(f"Refusing to download from unexpected host: {host}")
+
+
+def fetch_to(url: str, dest: Path, http: httpx.Client | None = None) -> Path:
+    _check_url(url)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    client = http or httpx.Client(timeout=httpx.Timeout(120, connect=20))
+    try:
+        with client.stream("GET", url, follow_redirects=False) as r:
+            if r.status_code != 200:
+                raise ApiError(f"Download failed: HTTP {r.status_code} for {url}", status=r.status_code)
+            with tmp.open("wb") as fh:
+                for chunk in r.iter_bytes(1 << 16):
+                    fh.write(chunk)
+    except httpx.HTTPError as e:
+        raise NetworkError(f"Download failed: {e}") from e
+    finally:
+        if http is None:
+            client.close()
+    tmp.replace(dest)
+    return dest
+
+
+def clip_metadata(clip: dict) -> dict:
+    op = clip.get("operation") or {}
+    lyrics = clip.get("lyrics") or {}
+    dur = clip.get("duration") or {}
+    return {
+        "id": clip.get("id"),
+        "title": clip.get("title"),
+        "duration_s": float(dur["value"]) if isinstance(dur, dict) and dur.get("value") else None,
+        "sound_prompt": op.get("sound_prompt"),
+        "lyrics": (lyrics.get("value") or {}).get("text") if isinstance(lyrics, dict) else None,
+        "op_type": clip.get("op_type"),
+        "conversation_id": op.get("conversation_id"),
+        "source_clip_id": op.get("source_clip_id"),
+        "created_at": clip.get("created_at"),
+        "privacy": clip.get("privacy"),
+        "wav_url": clip.get("wav_url"),
+        "audio_url": clip.get("audio_url"),
+        "image_url": clip.get("image_url"),
+        "web_url": f"https://www.flowmusic.app/song/{clip.get('id')}",
+    }
+
+
+def output_dir_for(base: Path, explicit: bool) -> Path:
+    return base if explicit else base / date.today().isoformat()
+
+
+def download_clip(
+    clip: dict,
+    out_dir: Path,
+    *,
+    formats: tuple[str, ...] = ("wav",),
+    cover: bool = False,
+    sidecar: bool = True,
+    http: httpx.Client | None = None,
+) -> dict:
+    """Download a clip; returns ``{"files": [...], "metadata": {...}}``."""
+    base = clip_basename(clip)
+    files: list[str] = []
+    for fmt in formats:
+        url = clip.get(FORMATS[fmt])
+        if not url and fmt == "wav" and clip.get("audio_url"):
+            fmt, url = "m4a", clip["audio_url"]  # fall back if no wav rendition
+        if not url:
+            raise ApiError(f"Clip {clip.get('id')} has no {fmt} audio (yet).")
+        files.append(str(fetch_to(url, out_dir / f"{base}.{fmt}", http)))
+    if cover and clip.get("image_url"):
+        files.append(str(fetch_to(clip["image_url"], out_dir / f"{base}.jpg", http)))
+    meta = clip_metadata(clip)
+    if sidecar:
+        p = out_dir / f"{base}.json"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(meta, indent=2, ensure_ascii=False), "utf-8")
+        files.append(str(p))
+    return {"files": files, "metadata": meta}
+
+
+def _sniff_ext(data: bytes) -> str:
+    if data[4:8] == b"ftyp":
+        return "m4a"
+    if data[:4] == b"RIFF":
+        return "wav"
+    if data[:3] == b"ID3" or data[:2] in (b"\xff\xfb", b"\xff\xf3"):
+        return "mp3"
+    if data[:4] == b"fLaC":
+        return "flac"
+    return "bin"
+
+
+def save_stems(clip: dict, stems: dict[str, str], out_dir: Path) -> list[str]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    base = clip_basename(clip)
+    files = []
+    for name, b64 in stems.items():
+        data = base64.b64decode(b64)
+        p = out_dir / f"{base}_{slugify(name)}.{_sniff_ext(data)}"
+        p.write_bytes(data)
+        files.append(str(p))
+    return files