feat: optional Hub upload for recordings + persistence docs

README.md

@@ -12,3 +12,28 @@ short_description: Collect microphone recordings for six spells
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Persistence of Recordings
+
+Recordings created via the UI are written at runtime into the `recordings/` folder inside the Space container. These files are NOT automatically versioned or shown in the repository file browser. To make them visible in the repo you must either:
+
+1. Commit them manually (e.g., pull the Space locally, copy files, `git add recordings/*.wav`, push).
+2. Or enable automatic upload using a Hugging Face token.
+
+### Automatic Upload (Recommended)
+
+Set a secret named `HF_TOKEN` in the Space settings (must have write access). Optionally set:
+
+- `HF_UPLOAD_REPO` target repo id (recommended: a dataset like `username/spell-recordings`).
+- `HF_UPLOAD_REPO_TYPE` one of `dataset` (default), `space`, or `model`.
+
+If `HF_UPLOAD_REPO` is omitted the current Space id is used (uploading into the Space repo when `HF_UPLOAD_REPO_TYPE=space`).
+
+Then check the "Upload to Hub" box before submitting. Each saved `.wav` file will be committed via the Hub API with a message like `Add recordings <timestamp>`.
+
+Uploads may take a few seconds. Large batches could hit rate limits; keep per-submit sizes modest.
+
+### Why You Don't See Runtime Files
+
+The repository view shows only Git-tracked content. Runtime-generated files live only in the ephemeral container filesystem until the Space restarts. Upload or commit them if you need persistence.
+

app.py

@@ -2,12 +2,17 @@ import os
 import re
 import time
 import math
-from typing import List, Tuple, Optional
+from typing import List, Tuple, Optional, Sequence
 
 import numpy as np
 import gradio as gr
 import soundfile as sf
 from scipy.signal import resample_poly
+try:
+    from huggingface_hub import HfApi, HfFolder
+except Exception:  # package might be missing in some local runs
+    HfApi = None
+    HfFolder = None
 
 # Output directory for saved recordings
 OUT_DIR = "recordings"
@@ -84,6 +89,53 @@ def save_one_from_path(filepath: Optional[str], spell: str, username: str) -> Op
     return out_path
 
 
+def upload_recordings(paths: Sequence[str]) -> Tuple[int, Optional[str]]:
+    """Upload given file paths to the Hub repo indicated by env HF_UPLOAD_REPO or the current Space repo.
+
+    Returns (uploaded_count, error_message). error_message is None on success.
+    Requires HF_TOKEN secret configured with write permission.
+    """
+    if not paths:
+        return 0, None
+    if HfApi is None:
+        return 0, "huggingface_hub not installed."
+    token = os.getenv("HF_TOKEN") or (HfFolder.get_token() if HfFolder else None)
+    if not token:
+        return 0, "No HF_TOKEN available (set as Space secret to enable uploads)."
+
+    repo_id = os.getenv("HF_UPLOAD_REPO")
+    # Best-effort infer the current Space repo id from environment if not provided
+    if not repo_id:
+        # In Spaces, SPACE_ID is like "username/space_name" for the current space.
+        # Use that as default so users can upload back to their Space if they want.
+        repo_id = os.getenv("SPACE_ID") or os.getenv("REPO_ID")
+    if not repo_id:
+        return 0, "Unable to infer target repo id (set HF_UPLOAD_REPO)."
+
+    api = HfApi(token=token)
+    uploaded = 0
+    commit_msg = f"Add recordings {int(time.time())}"
+    # repo_type: "dataset" (recommended) or "space" to commit to the Space repo
+    repo_type = os.getenv("HF_UPLOAD_REPO_TYPE", "dataset").lower()
+    if repo_type not in {"dataset", "space", "model"}:
+        repo_type = "dataset"
+    try:
+        for p in paths:
+            if not os.path.isfile(p):
+                continue
+            api.upload_file(
+                path_or_fileobj=p,
+                path_in_repo=f"recordings/{os.path.basename(p)}",
+                repo_id=repo_id,
+                repo_type=repo_type,
+                commit_message=commit_msg,
+            )
+            uploaded += 1
+    except Exception as e:  # broad catch to surface error in UI
+        return uploaded, f"Upload error: {e}"
+    return uploaded, None
+
+
 def submit_recordings(
     username: str,
     lumos_path: Optional[str],
@@ -92,6 +144,7 @@ def submit_recordings(
     wingardium_path: Optional[str],
     accio_path: Optional[str],
     reparo_path: Optional[str],
+    upload_flag: bool,
 ) -> str:
     user = sanitize_username(username)
 
@@ -107,16 +160,18 @@ def submit_recordings(
     saved = []
     skipped = []
 
+    saved_paths: List[str] = []
     for spell, path in pairs:
         out = save_one_from_path(path, spell, user)
         if out:
             saved.append(f"{spell} -> {os.path.basename(out)}")
+            saved_paths.append(out)
         else:
             skipped.append(spell)
 
     lines = []
     if saved:
-        lines.append("Saved recordings:")
+        lines.append("Saved recordings (local runtime):")
         lines += [f"- {s}" for s in saved]
     if skipped:
         lines.append("")
@@ -125,6 +180,15 @@ def submit_recordings(
     if not lines:
         return "No audio captured. Please record at least one spell."
 
+    if upload_flag:
+        uploaded, err = upload_recordings(saved_paths)
+        lines.append("")
+        if err:
+            lines.append(f"Hub upload attempted: {uploaded} succeeded, error: {err}")
+        else:
+            lines.append(f"Hub upload: {uploaded} file(s) committed to repo.")
+            lines.append("(It may take a few seconds to appear in the file browser.)")
+
     return "\n".join(lines)
 
 
@@ -150,20 +214,23 @@ def build_ui() -> gr.Blocks:
                 accio = gr.Audio(label="Accio", sources=["microphone", "upload"], type="filepath")
                 reparo = gr.Audio(label="Reparo", sources=["microphone", "upload"], type="filepath")
 
+        with gr.Row():
+            upload_checkbox = gr.Checkbox(label="Upload to Hub (requires HF_TOKEN)", value=False)
         submit = gr.Button("Submit")
         result = gr.Markdown()
 
         submit.click(
             fn=submit_recordings,
-            inputs=[username, lumos, nox, alohomora, wingardium, accio, reparo],
+            inputs=[username, lumos, nox, alohomora, wingardium, accio, reparo, upload_checkbox],
             outputs=[result],
         )
 
         gr.Markdown("""
-        Notes:
-        - Files are saved in the app's `recordings/` folder using: `<spell>_<username>_<timestamp>.wav`.
-        - 16 kHz mono WAV is used to make model training consistent.
-        - You don't have to record all spells at once—submit whatever you have.
+    Notes:
+    - Files are saved locally in `recordings/` with `<spell>_<username>_<timestamp>.wav`.
+    - Check "Upload to Hub" to commit them to the repo (needs HF_TOKEN secret).
+    - 16 kHz mono WAV ensures consistent model training.
+    - You can submit partial sets; only provided spells are saved.
         """)
 
     return demo

requirements.txt

@@ -1,4 +1,5 @@
 gradio
 numpy
 soundfile
-scipy
+scipy
+huggingface_hub