audiopod 2.1.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

audiopod/services/stem_extraction.py

@@ -0,0 +1,287 @@
+"""
+Stem Extraction Service - Audio stem separation
+"""
+
+from typing import List, Optional, Dict, Any, Literal
+from .base import BaseService
+from ..exceptions import ValidationError
+
+
+# Valid separation modes for the new API
+StemMode = Literal["single", "two", "four", "six", "producer", "studio", "mastering"]
+SingleStem = Literal["vocals", "drums", "bass", "guitar", "piano", "other", "instrumental"]
+
+
+class StemExtractionService(BaseService):
+    """
+    Service for audio stem separation.
+
+    Example:
+        ```python
+        from audiopod import Client
+
+        client = Client()
+
+        # Simple mode-based extraction (recommended)
+        result = client.stem_extraction.separate(
+            url="https://youtube.com/watch?v=VIDEO_ID",
+            mode="six"
+        )
+        for stem, url in result["download_urls"].items():
+            print(f"{stem}: {url}")
+
+        # Or extract only vocals
+        result = client.stem_extraction.separate(
+            file="song.mp3",
+            mode="single",
+            stem="vocals"
+        )
+        ```
+    """
+
+    def separate(
+        self,
+        file: Optional[str] = None,
+        url: Optional[str] = None,
+        mode: StemMode = "four",
+        stem: Optional[SingleStem] = None,
+        wait_for_completion: bool = True,
+        timeout: int = 900,
+    ) -> Dict[str, Any]:
+        """
+        Separate audio into stems using simple mode selection.
+
+        Args:
+            file: Path to local audio file
+            url: URL of audio/video (YouTube, SoundCloud, direct link)
+            mode: Separation mode:
+                - "single": Extract one stem (specify stem param)
+                - "two": Vocals + Instrumental
+                - "four": Vocals, Drums, Bass, Other (default)
+                - "six": Vocals, Drums, Bass, Guitar, Piano, Other
+                - "producer": 8 stems with kick, snare, hihat
+                - "studio": 12 stems for professional mixing
+                - "mastering": 16 stems maximum detail
+            stem: For mode="single", which stem to extract
+            wait_for_completion: Wait for job to complete (default: True)
+            timeout: Max wait time in seconds
+
+        Returns:
+            Job dict with id, status, download_urls (when completed)
+        """
+        if not file and not url:
+            raise ValidationError("Provide file or url")
+
+        if file and url:
+            raise ValidationError("Provide file or url, not both")
+
+        if mode == "single" and not stem:
+            raise ValidationError(
+                "stem parameter required for mode='single'. "
+                "Options: vocals, drums, bass, guitar, piano, other, instrumental"
+            )
+
+        data = {"mode": mode}
+        if stem:
+            data["stem"] = stem
+        if url:
+            data["url"] = url
+
+        files = self._prepare_file_upload(file, "file") if file else None
+
+        if self.async_mode:
+            return self._async_separate(data, files, wait_for_completion, timeout)
+
+        response = self.client.request(
+            "POST", "/api/v1/stem-extraction/api/extract", data=data, files=files
+        )
+
+        if wait_for_completion:
+            return self._wait_for_stem_job(response["id"], timeout)
+
+        return response
+
+    async def _async_separate(
+        self,
+        data: Dict[str, Any],
+        files: Optional[Dict[str, Any]],
+        wait_for_completion: bool,
+        timeout: int,
+    ) -> Dict[str, Any]:
+        response = await self.client.request(
+            "POST", "/api/v1/stem-extraction/api/extract", data=data, files=files
+        )
+        if wait_for_completion:
+            return await self._async_wait_for_stem_job(response["id"], timeout)
+        return response
+
+    def extract(
+        self,
+        file: Optional[str] = None,
+        url: Optional[str] = None,
+        mode: StemMode = "four",
+        stem: Optional[SingleStem] = None,
+    ) -> Dict[str, Any]:
+        """
+        Submit stem extraction job (returns immediately without waiting).
+
+        Use wait_for_completion() to poll for results.
+        """
+        return self.separate(file=file, url=url, mode=mode, stem=stem, wait_for_completion=False)
+
+    def wait_for_completion(self, job_id: int, timeout: int = 900) -> Dict[str, Any]:
+        """Wait for stem extraction job to complete."""
+        return self._wait_for_stem_job(job_id, timeout)
+
+    def status(self, job_id: int) -> Dict[str, Any]:
+        """Get stem extraction job status (alias for get_job)."""
+        return self.get_job(job_id)
+
+    def modes(self) -> Dict[str, Any]:
+        """Get available separation modes."""
+        if self.async_mode:
+            return self._async_modes()
+        return self.client.request("GET", "/api/v1/stem-extraction/modes")
+
+    async def _async_modes(self) -> Dict[str, Any]:
+        return await self.client.request("GET", "/api/v1/stem-extraction/modes")
+
+    # Legacy method - kept for backward compatibility
+    def extract_stems(
+        self,
+        audio_file: Optional[str] = None,
+        url: Optional[str] = None,
+        stem_types: Optional[List[str]] = None,
+        model_name: str = "htdemucs",
+        two_stems_mode: Optional[str] = None,
+        wait_for_completion: bool = False,
+        timeout: int = 900,
+    ) -> Dict[str, Any]:
+        """
+        Extract stems from audio (legacy method).
+
+        For new code, use separate() instead which uses the simpler mode-based API.
+
+        Args:
+            audio_file: Path to local audio file
+            url: URL of audio file (alternative to audio_file)
+            stem_types: Stems to extract (e.g., ["vocals", "drums", "bass", "other"])
+            model_name: Model to use ("htdemucs" or "htdemucs_6s")
+            two_stems_mode: Two-stem mode ("vocals", "drums", or "bass")
+            wait_for_completion: Wait for job to complete
+            timeout: Max wait time in seconds
+
+        Returns:
+            Job dict with id, status, download_urls (when completed)
+        """
+        if not audio_file and not url:
+            raise ValidationError("Provide audio_file or url")
+
+        if audio_file and url:
+            raise ValidationError("Provide audio_file or url, not both")
+
+        if stem_types is None:
+            stem_types = (
+                ["vocals", "drums", "bass", "other", "piano", "guitar"]
+                if model_name == "htdemucs_6s"
+                else ["vocals", "drums", "bass", "other"]
+            )
+
+        data = {"stem_types": str(stem_types), "model_name": model_name}
+
+        if url:
+            data["url"] = url
+
+        if two_stems_mode:
+            data["two_stems_mode"] = two_stems_mode
+
+        files = self._prepare_file_upload(audio_file, "file") if audio_file else None
+
+        if self.async_mode:
+            return self._async_extract_stems(data, files, wait_for_completion, timeout)
+
+        response = self.client.request(
+            "POST", "/api/v1/stem-extraction/extract", data=data, files=files
+        )
+
+        if wait_for_completion:
+            return self._wait_for_stem_job(response["id"], timeout)
+
+        return response
+
+    async def _async_extract_stems(
+        self,
+        data: Dict[str, Any],
+        files: Optional[Dict[str, Any]],
+        wait_for_completion: bool,
+        timeout: int,
+    ) -> Dict[str, Any]:
+        response = await self.client.request(
+            "POST", "/api/v1/stem-extraction/extract", data=data, files=files
+        )
+        if wait_for_completion:
+            return await self._async_wait_for_stem_job(response["id"], timeout)
+        return response
+
+    def get_job(self, job_id: int) -> Dict[str, Any]:
+        """Get stem extraction job status."""
+        if self.async_mode:
+            return self._async_get_job(job_id)
+        return self.client.request("GET", f"/api/v1/stem-extraction/status/{job_id}")
+
+    async def _async_get_job(self, job_id: int) -> Dict[str, Any]:
+        return await self.client.request("GET", f"/api/v1/stem-extraction/status/{job_id}")
+
+    def list_jobs(self, skip: int = 0, limit: int = 50) -> List[Dict[str, Any]]:
+        """List stem extraction jobs."""
+        if self.async_mode:
+            return self._async_list_jobs(skip, limit)
+        return self.client.request(
+            "GET", "/api/v1/stem-extraction/jobs", params={"skip": skip, "limit": limit}
+        )
+
+    async def _async_list_jobs(self, skip: int, limit: int) -> List[Dict[str, Any]]:
+        return await self.client.request(
+            "GET", "/api/v1/stem-extraction/jobs", params={"skip": skip, "limit": limit}
+        )
+
+    def delete_job(self, job_id: int) -> Dict[str, str]:
+        """Delete a stem extraction job."""
+        if self.async_mode:
+            return self._async_delete_job(job_id)
+        return self.client.request("DELETE", f"/api/v1/stem-extraction/jobs/{job_id}")
+
+    async def _async_delete_job(self, job_id: int) -> Dict[str, str]:
+        return await self.client.request("DELETE", f"/api/v1/stem-extraction/jobs/{job_id}")
+
+    def _wait_for_stem_job(self, job_id: int, timeout: int = 900) -> Dict[str, Any]:
+        """Wait for stem job completion."""
+        import time
+
+        start = time.time()
+        while time.time() - start < timeout:
+            job = self.get_job(job_id)
+            status = job.get("status", "").upper()
+            if status == "COMPLETED":
+                return job
+            elif status in ["FAILED", "ERROR"]:
+                raise Exception(f"Job failed: {job.get('error_message', 'Unknown')}")
+            time.sleep(5)
+        raise TimeoutError(f"Job {job_id} timed out after {timeout}s")
+
+    async def _async_wait_for_stem_job(self, job_id: int, timeout: int = 900) -> Dict[str, Any]:
+        """Async wait for stem job completion."""
+        import asyncio
+        import time
+
+        start = time.time()
+        while time.time() - start < timeout:
+            job = await self.get_job(job_id)
+            status = job.get("status", "").upper()
+            if status == "COMPLETED":
+                return job
+            elif status in ["FAILED", "ERROR"]:
+                raise Exception(f"Job failed: {job.get('error_message', 'Unknown')}")
+            await asyncio.sleep(5)
+        raise TimeoutError(f"Job {job_id} timed out after {timeout}s")
+

audiopod/services/transcription.py

@@ -0,0 +1,210 @@
+"""
+Transcription Service - Speech-to-text
+
+API Routes:
+- POST /api/v1/transcription/transcribe        - Transcribe from URL
+- POST /api/v1/transcription/transcribe-upload - Transcribe from file upload
+- GET  /api/v1/transcription/jobs/{id}         - Get job details
+- GET  /api/v1/transcription/jobs              - List jobs
+- DELETE /api/v1/transcription/jobs/{id}       - Delete job
+"""
+
+from typing import Optional, Dict, Any, List
+from .base import BaseService
+
+
+class TranscriptionService(BaseService):
+    """Service for speech-to-text transcription."""
+
+    def create(
+        self,
+        file: Optional[str] = None,
+        url: Optional[str] = None,
+        language: Optional[str] = None,
+        speaker_diarization: bool = False,
+        wait_for_completion: bool = False,
+        timeout: int = 600,
+    ) -> Dict[str, Any]:
+        """Alias for transcribe() - matches Node.js SDK."""
+        return self.transcribe(
+            audio_file=file,
+            url=url,
+            language=language,
+            speaker_diarization=speaker_diarization,
+            wait_for_completion=wait_for_completion,
+            timeout=timeout,
+        )
+
+    def transcribe(
+        self,
+        audio_file: Optional[str] = None,
+        url: Optional[str] = None,
+        language: Optional[str] = None,
+        speaker_diarization: bool = False,
+        wait_for_completion: bool = False,
+        timeout: int = 600,
+    ) -> Dict[str, Any]:
+        """
+        Transcribe audio to text.
+
+        Args:
+            audio_file: Path to local audio file
+            url: URL of audio file (or list of URLs)
+            language: Language code (auto-detected if not provided)
+            speaker_diarization: Enable speaker separation
+            wait_for_completion: Wait for completion
+            timeout: Max wait time in seconds
+
+        Returns:
+            Job dict with transcript when completed
+        """
+        if audio_file:
+            # File upload endpoint
+            data = {
+                "enable_speaker_diarization": speaker_diarization,
+            }
+            if language:
+                data["language"] = language
+
+            files = self._prepare_file_upload(audio_file, "files")
+
+            if self.async_mode:
+                return self._async_transcribe_upload(data, files, wait_for_completion, timeout)
+
+            response = self.client.request(
+                "POST", "/api/v1/transcription/transcribe-upload", data=data, files=files
+            )
+        else:
+            # URL-based endpoint
+            data = {
+                "source_urls": [url] if isinstance(url, str) else url,
+                "enable_speaker_diarization": speaker_diarization,
+            }
+            if language:
+                data["language"] = language
+
+            if self.async_mode:
+                return self._async_transcribe(data, wait_for_completion, timeout)
+
+            response = self.client.request(
+                "POST", "/api/v1/transcription/transcribe", json_data=data
+            )
+
+        if wait_for_completion:
+            job_id = response.get("id") or response.get("job_id")
+            return self._wait_for_transcription(job_id, timeout)
+        return response
+
+    async def _async_transcribe(
+        self, data: Dict, wait_for_completion: bool, timeout: int
+    ) -> Dict[str, Any]:
+        response = await self.client.request(
+            "POST", "/api/v1/transcription/transcribe", json_data=data
+        )
+        if wait_for_completion:
+            job_id = response.get("id") or response.get("job_id")
+            return await self._async_wait_for_transcription(job_id, timeout)
+        return response
+
+    async def _async_transcribe_upload(
+        self, data: Dict, files: Dict, wait_for_completion: bool, timeout: int
+    ) -> Dict[str, Any]:
+        response = await self.client.request(
+            "POST", "/api/v1/transcription/transcribe-upload", data=data, files=files
+        )
+        if wait_for_completion:
+            job_id = response.get("id") or response.get("job_id")
+            return await self._async_wait_for_transcription(job_id, timeout)
+        return response
+
+    def get_job(self, job_id: int) -> Dict[str, Any]:
+        """Get transcription job details and status."""
+        if self.async_mode:
+            return self._async_get_job(job_id)
+        return self.client.request("GET", f"/api/v1/transcription/jobs/{job_id}")
+
+    async def _async_get_job(self, job_id: int) -> Dict[str, Any]:
+        return await self.client.request("GET", f"/api/v1/transcription/jobs/{job_id}")
+
+    def list_jobs(self, skip: int = 0, limit: int = 50) -> List[Dict[str, Any]]:
+        """List transcription jobs."""
+        if self.async_mode:
+            return self._async_list_jobs(skip, limit)
+        return self.client.request(
+            "GET", "/api/v1/transcription/jobs", params={"skip": skip, "limit": limit}
+        )
+
+    async def _async_list_jobs(self, skip: int, limit: int) -> List[Dict[str, Any]]:
+        return await self.client.request(
+            "GET", "/api/v1/transcription/jobs", params={"skip": skip, "limit": limit}
+        )
+
+    def delete_job(self, job_id: int) -> Dict[str, str]:
+        """Delete a transcription job."""
+        if self.async_mode:
+            return self._async_delete_job(job_id)
+        return self.client.request("DELETE", f"/api/v1/transcription/jobs/{job_id}")
+
+    async def _async_delete_job(self, job_id: int) -> Dict[str, str]:
+        return await self.client.request("DELETE", f"/api/v1/transcription/jobs/{job_id}")
+
+    def get_transcript(self, job_id: int, format: str = "json") -> Any:
+        """
+        Get transcript content.
+        
+        Args:
+            job_id: Job ID
+            format: Output format - 'json', 'txt', 'srt', 'vtt'
+        """
+        if self.async_mode:
+            return self._async_get_transcript(job_id, format)
+        return self.client.request(
+            "GET", f"/api/v1/transcription/jobs/{job_id}/transcript", params={"format": format}
+        )
+
+    async def _async_get_transcript(self, job_id: int, format: str) -> Any:
+        return await self.client.request(
+            "GET", f"/api/v1/transcription/jobs/{job_id}/transcript", params={"format": format}
+        )
+
+    def wait_for_completion(self, job_id: int, timeout: int = 600) -> Dict[str, Any]:
+        """Wait for transcription job completion (matches Node.js SDK)."""
+        return self._wait_for_transcription(job_id, timeout)
+
+    def _wait_for_transcription(self, job_id: int, timeout: int) -> Dict[str, Any]:
+        """Wait for transcription job completion."""
+        import time
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            job = self.get_job(job_id)
+            status = job.get("status", "").upper()
+
+            if status == "COMPLETED":
+                return job
+            elif status in ("FAILED", "ERROR", "CANCELLED"):
+                raise Exception(f"Transcription failed: {job.get('error_message', 'Unknown error')}")
+
+            time.sleep(3)
+
+        raise TimeoutError(f"Transcription {job_id} did not complete within {timeout} seconds")
+
+    async def _async_wait_for_transcription(self, job_id: int, timeout: int) -> Dict[str, Any]:
+        """Async wait for transcription job completion."""
+        import asyncio
+        import time
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            job = await self.get_job(job_id)
+            status = job.get("status", "").upper()
+
+            if status == "COMPLETED":
+                return job
+            elif status in ("FAILED", "ERROR", "CANCELLED"):
+                raise Exception(f"Transcription failed: {job.get('error_message', 'Unknown error')}")
+
+            await asyncio.sleep(3)
+
+        raise TimeoutError(f"Transcription {job_id} did not complete within {timeout} seconds")
+

audiopod/services/translation.py

@@ -0,0 +1,135 @@
+"""
+Translation Service - Audio/speech translation
+
+API Routes:
+- POST /api/v1/translation/translate/speech   - Translate speech
+- GET  /api/v1/translation/translations/{id}  - Get translation job
+- GET  /api/v1/translation/translations       - List translations
+- DELETE /api/v1/translation/translations/{id} - Delete translation
+"""
+
+from typing import Optional, Dict, Any, List
+from .base import BaseService
+
+
+class TranslationService(BaseService):
+    """Service for audio translation."""
+
+    def translate(
+        self,
+        audio_file: Optional[str] = None,
+        url: Optional[str] = None,
+        target_language: str = "en",
+        source_language: Optional[str] = None,
+        wait_for_completion: bool = False,
+        timeout: int = 900,
+    ) -> Dict[str, Any]:
+        """
+        Translate audio to another language.
+
+        Args:
+            audio_file: Path to local audio file
+            url: URL of audio file
+            target_language: Target language code
+            source_language: Source language (auto-detected if not provided)
+            wait_for_completion: Wait for completion
+            timeout: Max wait time in seconds
+
+        Returns:
+            Job dict with translated audio URL when completed
+        """
+        data = {"target_language": target_language}
+        if source_language:
+            data["source_language"] = source_language
+        if url:
+            data["url"] = url
+
+        files = self._prepare_file_upload(audio_file, "file") if audio_file else None
+
+        if self.async_mode:
+            return self._async_translate(data, files, wait_for_completion, timeout)
+
+        response = self.client.request("POST", "/api/v1/translation/translate/speech", data=data, files=files)
+
+        if wait_for_completion:
+            job_id = response.get("id") or response.get("job_id")
+            return self._wait_for_translation(job_id, timeout)
+        return response
+
+    async def _async_translate(
+        self, data: Dict, files: Optional[Dict], wait_for_completion: bool, timeout: int
+    ) -> Dict[str, Any]:
+        response = await self.client.request("POST", "/api/v1/translation/translate/speech", data=data, files=files)
+        if wait_for_completion:
+            job_id = response.get("id") or response.get("job_id")
+            return await self._async_wait_for_translation(job_id, timeout)
+        return response
+
+    def get_job(self, job_id: int) -> Dict[str, Any]:
+        """Get translation job details and status."""
+        if self.async_mode:
+            return self._async_get_job(job_id)
+        return self.client.request("GET", f"/api/v1/translation/translations/{job_id}")
+
+    async def _async_get_job(self, job_id: int) -> Dict[str, Any]:
+        return await self.client.request("GET", f"/api/v1/translation/translations/{job_id}")
+
+    def list_jobs(self, skip: int = 0, limit: int = 50) -> List[Dict[str, Any]]:
+        """List translation jobs."""
+        if self.async_mode:
+            return self._async_list_jobs(skip, limit)
+        return self.client.request(
+            "GET", "/api/v1/translation/translations", params={"skip": skip, "limit": limit}
+        )
+
+    async def _async_list_jobs(self, skip: int, limit: int) -> List[Dict[str, Any]]:
+        return await self.client.request(
+            "GET", "/api/v1/translation/translations", params={"skip": skip, "limit": limit}
+        )
+
+    def delete_job(self, job_id: int) -> Dict[str, str]:
+        """Delete a translation job."""
+        if self.async_mode:
+            return self._async_delete_job(job_id)
+        return self.client.request("DELETE", f"/api/v1/translation/translations/{job_id}")
+
+    async def _async_delete_job(self, job_id: int) -> Dict[str, str]:
+        return await self.client.request("DELETE", f"/api/v1/translation/translations/{job_id}")
+
+    def _wait_for_translation(self, job_id: int, timeout: int) -> Dict[str, Any]:
+        """Wait for translation job completion."""
+        import time
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            job = self.get_job(job_id)
+            status = job.get("status", "").upper()
+
+            if status == "COMPLETED":
+                return job
+            elif status in ("FAILED", "ERROR"):
+                raise Exception(f"Translation failed: {job.get('error_message', 'Unknown error')}")
+
+            time.sleep(5)
+
+        raise TimeoutError(f"Translation {job_id} did not complete within {timeout} seconds")
+
+    async def _async_wait_for_translation(self, job_id: int, timeout: int) -> Dict[str, Any]:
+        """Async wait for translation job completion."""
+        import asyncio
+        import time
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            job = await self.get_job(job_id)
+            status = job.get("status", "").upper()
+
+            if status == "COMPLETED":
+                return job
+            elif status in ("FAILED", "ERROR"):
+                raise Exception(f"Translation failed: {job.get('error_message', 'Unknown error')}")
+
+            await asyncio.sleep(5)
+
+        raise TimeoutError(f"Translation {job_id} did not complete within {timeout} seconds")
+