audiopod 1.1.0__tar.gz → 1.1.1__tar.gz

{audiopod-1.1.0 → audiopod-1.1.1}/CHANGELOG.md

@@ -5,6 +5,85 @@ All notable changes to the AudioPod Python SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2024-12-15
+
+### 🔧 Translation Service Fixes
+
+This release fixes the translation service to use the proper speech-to-speech translation endpoint and adds enhanced functionality.
+
+### ✨ Added
+
+- **Speech-to-Speech Translation**: Now uses the correct `/api/v1/translation/translate/speech` endpoint
+  - Preserves original speaker voice characteristics during translation
+  - Supports both audio and video file translation
+  - Maintains speaker separation in multi-speaker content
+
+- **URL-Based Translation**: Support for translating audio/video from URLs
+  - Direct media URL support (YouTube, audio links, etc.)
+  - No need to download files locally first
+
+- **Enhanced Translation Job Management**:
+  - `list_translation_jobs()` - List translation history with pagination
+  - `retry_translation()` - Retry failed translation jobs
+  - `delete_translation_job()` - Delete translation jobs
+  - `translate_speech()` - Alias method for clearer API
+
+### 🔧 Fixed
+
+- **Translation Endpoint**: Changed from generic `/translate` to speech-specific `/translate/speech`
+- **API Schema Alignment**: Request and response formats now match the actual API
+- **Response Model**: Updated `TranslationResult` to include all API response fields:
+  - `translated_audio_url` - Direct URL to translated audio
+  - `video_output_url` - Translated video output (when applicable)
+  - `transcript_urls` - Transcript files in multiple formats
+  - `display_name` - Original file display name
+  - `is_video` - Whether the input was a video file
+
+### 🏗️ Improved
+
+- **Better Error Handling**: Enhanced validation for file vs URL inputs
+- **Backward Compatibility**: Maintained `audio_output_url` property for existing code
+- **Enhanced Examples**: Updated documentation and examples to show new features
+- **Type Safety**: Improved type hints and validation
+
+### 📚 Documentation
+
+- **Updated Examples**: `basic_usage.py` now demonstrates speech-to-speech translation
+- **README Updates**: Corrected API usage examples with proper endpoint usage
+- **Method Documentation**: Enhanced docstrings with accurate parameter descriptions
+
+### 🚀 Usage Examples
+
+#### Fixed Speech Translation
+```python
+# Speech-to-speech translation (preserves voice characteristics)
+translation = client.translation.translate_speech(
+    audio_file="english_speech.wav",
+    target_language="es",  # Spanish
+    source_language="en",  # Optional - auto-detect
+    wait_for_completion=True
+)
+
+# URL-based translation
+url_translation = client.translation.translate_speech(
+    url="https://example.com/audio.mp3",
+    target_language="fr",  # French
+    wait_for_completion=True
+)
+
+# Job management
+jobs = client.translation.list_translation_jobs(limit=10)
+retry_job = client.translation.retry_translation(failed_job_id)
+```
+
+### 🔄 Migration Notes
+
+- **No Breaking Changes**: Existing `translate_audio()` method continues to work
+- **Enhanced Functionality**: Now uses proper speech-to-speech endpoint automatically
+- **New Properties**: Additional response fields available in `TranslationResult`
+
+---
+
 ## [1.1.0] - 2024-01-15
 
 ### 🎉 Major API Compatibility Update

{audiopod-1.1.0 → audiopod-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiopod
-Version: 1.1.0
+Version: 1.1.1
 Summary: Professional Audio Processing API Client for Python
 Home-page: https://github.com/audiopod-ai/audiopod-python
 Author: AudioPod AI
@@ -142,17 +142,25 @@ print(f"Transcript: {transcript.transcript}")
 print(f"Detected {len(transcript.segments)} speakers")
 ```
 
-#### Audio Translation
+#### Speech-to-Speech Translation
 
 ```python
-# Translate audio to another language
-translation = client.translation.translate_audio(
+# Translate speech while preserving voice characteristics
+translation = client.translation.translate_speech(
     audio_file="path/to/english_audio.wav",
     target_language="es",  # Spanish
+    source_language="en",  # English (optional - auto-detect)
     wait_for_completion=True
 )
 
-print(f"Translated audio URL: {translation.audio_output_url}")
+print(f"Translated audio URL: {translation.translated_audio_url}")
+
+# Or translate from URL
+url_translation = client.translation.translate_speech(
+    url="https://example.com/audio.mp3",
+    target_language="fr",  # French
+    wait_for_completion=True
+)
 ```
 
 ### Async Support

{audiopod-1.1.0 → audiopod-1.1.1}/README.md

@@ -90,17 +90,25 @@ print(f"Transcript: {transcript.transcript}")
 print(f"Detected {len(transcript.segments)} speakers")
 ```
 
-#### Audio Translation
+#### Speech-to-Speech Translation
 
 ```python
-# Translate audio to another language
-translation = client.translation.translate_audio(
+# Translate speech while preserving voice characteristics
+translation = client.translation.translate_speech(
     audio_file="path/to/english_audio.wav",
     target_language="es",  # Spanish
+    source_language="en",  # English (optional - auto-detect)
     wait_for_completion=True
 )
 
-print(f"Translated audio URL: {translation.audio_output_url}")
+print(f"Translated audio URL: {translation.translated_audio_url}")
+
+# Or translate from URL
+url_translation = client.translation.translate_speech(
+    url="https://example.com/audio.mp3",
+    target_language="fr",  # French
+    wait_for_completion=True
+)
 ```
 
 ### Async Support

{audiopod-1.1.0 → audiopod-1.1.1}/audiopod/__init__.py

@@ -47,7 +47,7 @@ from .models import (
     TranslationResult
 )
 
-__version__ = "1.1.0"
+__version__ = "1.1.1"
 __author__ = "AudioPod AI"
 __email__ = "support@audiopod.ai"
 __license__ = "MIT"

{audiopod-1.1.0 → audiopod-1.1.1}/audiopod/models.py

@@ -151,13 +151,18 @@ class MusicGenerationResult:
 
 @dataclass
 class TranslationResult:
-    """Translation job result"""
+    """Speech translation job result"""
     job: Job
     source_language: Optional[str] = None
     target_language: Optional[str] = None
-    audio_output_url: Optional[str] = None
-    video_output_url: Optional[str] = None
+    display_name: Optional[str] = None
+    audio_output_path: Optional[str] = None
+    video_output_path: Optional[str] = None
     transcript_path: Optional[str] = None
+    translated_audio_url: Optional[str] = None
+    video_output_url: Optional[str] = None
+    transcript_urls: Optional[Dict[str, str]] = None
+    is_video: bool = False
     
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> 'TranslationResult':
@@ -166,10 +171,20 @@ class TranslationResult:
             job=Job.from_dict(data),
             source_language=data.get('source_language'),
             target_language=data.get('target_language'),
-            audio_output_url=data.get('audio_output_path'),
-            video_output_url=data.get('video_output_path'),
-            transcript_path=data.get('transcript_path')
+            display_name=data.get('display_name'),
+            audio_output_path=data.get('audio_output_path'),
+            video_output_path=data.get('video_output_path'),
+            transcript_path=data.get('transcript_path'),
+            translated_audio_url=data.get('translated_audio_url'),
+            video_output_url=data.get('video_output_url'),
+            transcript_urls=data.get('transcript_urls'),
+            is_video=data.get('is_video', False)
         )
+    
+    @property
+    def audio_output_url(self) -> Optional[str]:
+        """Backward compatibility property - returns translated_audio_url"""
+        return self.translated_audio_url
 
 
 @dataclass

audiopod-1.1.1/audiopod/services/translation.py

@@ -0,0 +1,196 @@
+"""
+Translation Service - Speech-to-speech translation operations
+"""
+
+from typing import Optional, Union
+from .base import BaseService
+from ..models import Job, TranslationResult
+from ..exceptions import ValidationError
+
+
+class TranslationService(BaseService):
+    """Service for speech-to-speech translation operations"""
+    
+    def translate_audio(
+        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
+    ) -> Union[Job, TranslationResult]:
+        """
+        Translate speech from audio/video file to another language while preserving voice characteristics
+        
+        Args:
+            audio_file: Path to audio/video file (required if no URL)
+            url: Direct media URL (required if no file)
+            target_language: Target language code (ISO 639-1, e.g., 'es' for Spanish)
+            source_language: Source language code (auto-detect if None)
+            wait_for_completion: Whether to wait for completion
+            timeout: Maximum time to wait
+            
+        Returns:
+            Job object or translation result
+        """
+        if not audio_file and not url:
+            raise ValidationError("Either audio_file or url must be provided")
+        
+        if audio_file and url:
+            raise ValidationError("Provide either audio_file or url, not both")
+            
+        target_language = self._validate_language_code(target_language)
+        if source_language:
+            source_language = self._validate_language_code(source_language)
+            
+        # Prepare request data
+        files = {}
+        data = {"target_language": target_language}
+        
+        if audio_file:
+            files = self._prepare_file_upload(audio_file, "file")
+        
+        if url:
+            data["url"] = url
+            
+        if source_language:
+            data["source_language"] = source_language
+            
+        if self.async_mode:
+            return self._async_translate_audio(files, data, wait_for_completion, timeout)
+        else:
+            response = self.client.request(
+                "POST", 
+                "/api/v1/translation/translate/speech",  # FIXED: Use correct speech-to-speech endpoint
+                data=data, 
+                files=files if files else None
+            )
+            job = Job.from_dict(response)
+            
+            if wait_for_completion:
+                completed_job = self._wait_for_completion(job.id, timeout)
+                return TranslationResult.from_dict(completed_job.result or completed_job.__dict__)
+                
+            return job
+    
+    def translate_speech(
+        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
+    ) -> Union[Job, TranslationResult]:
+        """
+        Alias for translate_audio - more descriptive method name for speech translation
+        """
+        return self.translate_audio(
+            audio_file=audio_file,
+            url=url,
+            target_language=target_language,
+            source_language=source_language,
+            wait_for_completion=wait_for_completion,
+            timeout=timeout
+        )
+            
+    async def _async_translate_audio(self, files, data, wait_for_completion, timeout):
+        """Async version of translate_audio"""
+        response = await self.client.request(
+            "POST", 
+            "/api/v1/translation/translate/speech",  # FIXED: Use correct speech-to-speech endpoint
+            data=data, 
+            files=files if files else None
+        )
+        job = Job.from_dict(response)
+        
+        if wait_for_completion:
+            completed_job = await self._async_wait_for_completion(job.id, timeout)
+            return TranslationResult.from_dict(completed_job.result or completed_job.__dict__)
+            
+        return job
+        
+    def get_translation_job(self, job_id: int) -> TranslationResult:
+        """Get translation job details"""
+        if self.async_mode:
+            return self._async_get_translation_job(job_id)
+        else:
+            response = self.client.request("GET", f"/api/v1/translation/translations/{job_id}")
+            return TranslationResult.from_dict(response)
+            
+    async def _async_get_translation_job(self, job_id: int) -> TranslationResult:
+        """Async version of get_translation_job"""
+        response = await self.client.request("GET", f"/api/v1/translation/translations/{job_id}")
+        return TranslationResult.from_dict(response)
+    
+    def list_translation_jobs(
+        self,
+        skip: int = 0,
+        limit: int = 50
+    ) -> list:
+        """
+        List translation jobs
+        
+        Args:
+            skip: Number of jobs to skip (pagination offset)
+            limit: Maximum number of jobs to return (max 100)
+            
+        Returns:
+            List of translation jobs
+        """
+        params = {
+            "skip": skip,
+            "limit": min(limit, 100)  # API max is 100
+        }
+        
+        if self.async_mode:
+            return self._async_list_translation_jobs(params)
+        else:
+            response = self.client.request("GET", "/api/v1/translation/translations", params=params)
+            return [TranslationResult.from_dict(job_data) for job_data in response]
+    
+    async def _async_list_translation_jobs(self, params: dict) -> list:
+        """Async version of list_translation_jobs"""
+        response = await self.client.request("GET", "/api/v1/translation/translations", params=params)
+        return [TranslationResult.from_dict(job_data) for job_data in response]
+    
+    def retry_translation(self, job_id: int) -> Job:
+        """
+        Retry a failed translation job
+        
+        Args:
+            job_id: ID of the failed translation job to retry
+            
+        Returns:
+            New job object for the retry attempt
+        """
+        if self.async_mode:
+            return self._async_retry_translation(job_id)
+        else:
+            response = self.client.request("POST", f"/api/v1/translation/translations/{job_id}/retry")
+            return Job.from_dict(response)
+    
+    async def _async_retry_translation(self, job_id: int) -> Job:
+        """Async version of retry_translation"""
+        response = await self.client.request("POST", f"/api/v1/translation/translations/{job_id}/retry")
+        return Job.from_dict(response)
+    
+    def delete_translation_job(self, job_id: int) -> dict:
+        """
+        Delete a translation job
+        
+        Args:
+            job_id: ID of the translation job to delete
+            
+        Returns:
+            Deletion confirmation
+        """
+        if self.async_mode:
+            return self._async_delete_translation_job(job_id)
+        else:
+            return self.client.request("DELETE", f"/api/v1/translation/translations/{job_id}")
+    
+    async def _async_delete_translation_job(self, job_id: int) -> dict:
+        """Async version of delete_translation_job"""
+        return await self.client.request("DELETE", f"/api/v1/translation/translations/{job_id}")

{audiopod-1.1.0 → audiopod-1.1.1}/examples/basic_usage.py

@@ -227,8 +227,8 @@ def transcription_example(client):
 
 
 def translation_example(client):
-    """Demonstrate audio translation"""
-    print("\n🌍 Translation Example")
+    """Demonstrate speech-to-speech translation"""
+    print("\n🌍 Speech Translation Example")
     print("=" * 50)
     
     audio_file = "examples/english_speech.wav"
@@ -236,23 +236,59 @@ def translation_example(client):
     if not Path(audio_file).exists():
         print(f"⚠️  Audio file not found: {audio_file}")
         print("   Please provide an English audio file to test translation")
+        print("   Alternatively, you can use a URL - see example below")
+        
+        # Show URL-based translation example
+        try:
+            print("\n🔄 Trying URL-based translation example...")
+            
+            translation_job = client.translation.translate_speech(
+                url="https://example.com/sample_english.wav",  # Example URL
+                target_language="es",  # Spanish
+                source_language="en",   # English
+                wait_for_completion=False  # Don't wait for this example
+            )
+            
+            print(f"📋 URL translation job started: {translation_job.id}")
+            print("   Note: This is just an example - replace with a real audio URL")
+            
+        except AudioPodError as e:
+            print(f"   Expected error (example URL): {e.message}")
+        
         return
     
     try:
-        print(f"🔄 Translating audio to Spanish...")
+        print(f"🔄 Translating speech to Spanish (preserving voice characteristics)...")
         
         translation_job = client.translation.translate_audio(
             audio_file=audio_file,
             target_language="es",  # Spanish
-            source_language="en",  # English
+            source_language="en",  # English (optional - auto-detect if not specified)
             wait_for_completion=True,
             timeout=900  # 15 minutes for translation
         )
         
-        print("✅ Translation completed!")
-        print(f"🎵 Translated audio: {translation_job.audio_output_url}")
+        print("✅ Speech translation completed!")
+        print(f"🎵 Translated audio: {translation_job.translated_audio_url}")
+        print(f"🎬 Video output: {translation_job.video_output_url}")
         print(f"📝 Source language: {translation_job.source_language}")
         print(f"🎯 Target language: {translation_job.target_language}")
+        print(f"📄 Display name: {translation_job.display_name}")
+        
+        if translation_job.transcript_urls:
+            print("📋 Transcript URLs:")
+            for format_type, url in translation_job.transcript_urls.items():
+                print(f"   {format_type}: {url}")
+        
+        # Demonstrate additional translation methods
+        print("\n🔄 Demonstrating job management...")
+        
+        # List recent translation jobs
+        jobs = client.translation.list_translation_jobs(limit=5)
+        print(f"📋 Found {len(jobs)} recent translation jobs")
+        
+        # Show job retry capability (don't actually retry)
+        print(f"🔄 Job retry available for failed jobs: translation.retry_translation({translation_job.job.id})")
         
     except AudioPodError as e:
         print(f"❌ Translation error: {e.message}")

{audiopod-1.1.0 → audiopod-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "audiopod"
-version = "1.1.0"
+version = "1.1.1"
 authors = [
     {name = "AudioPod AI", email = "support@audiopod.ai"},
 ]

audiopod-1.1.0/audiopod/services/translation.py

@@ -1,81 +0,0 @@
-"""
-Translation Service - Audio/video translation operations
-"""
-
-from typing import Optional, Union
-from .base import BaseService
-from ..models import Job, TranslationResult
-
-
-class TranslationService(BaseService):
-    """Service for audio and video translation operations"""
-    
-    def translate_audio(
-        self,
-        audio_file: str,
-        target_language: str,
-        source_language: Optional[str] = None,
-        wait_for_completion: bool = False,
-        timeout: int = 900
-    ) -> Union[Job, TranslationResult]:
-        """
-        Translate audio to another language
-        
-        Args:
-            audio_file: Path to audio file
-            target_language: Target language code
-            source_language: Source language (auto-detect if None)
-            wait_for_completion: Whether to wait for completion
-            timeout: Maximum time to wait
-            
-        Returns:
-            Job object or translation result
-        """
-        target_language = self._validate_language_code(target_language)
-        if source_language:
-            source_language = self._validate_language_code(source_language)
-            
-        files = self._prepare_file_upload(audio_file, "file")
-        data = {"target_language": target_language}
-        if source_language:
-            data["source_language"] = source_language
-            
-        if self.async_mode:
-            return self._async_translate_audio(files, data, wait_for_completion, timeout)
-        else:
-            response = self.client.request(
-                "POST", "/api/v1/translation/translate", data=data, files=files
-            )
-            job = Job.from_dict(response)
-            
-            if wait_for_completion:
-                completed_job = self._wait_for_completion(job.id, timeout)
-                return TranslationResult.from_dict(completed_job.result or completed_job.__dict__)
-                
-            return job
-            
-    async def _async_translate_audio(self, files, data, wait_for_completion, timeout):
-        """Async version of translate_audio"""
-        response = await self.client.request(
-            "POST", "/api/v1/translation/translate", data=data, files=files
-        )
-        job = Job.from_dict(response)
-        
-        if wait_for_completion:
-            completed_job = await self._async_wait_for_completion(job.id, timeout)
-            return TranslationResult.from_dict(completed_job.result or completed_job.__dict__)
-            
-        return job
-        
-    def get_translation_job(self, job_id: int) -> TranslationResult:
-        """Get translation job details"""
-        if self.async_mode:
-            return self._async_get_translation_job(job_id)
-        else:
-            response = self.client.request("GET", f"/api/v1/translation/translations/{job_id}")
-            return TranslationResult.from_dict(response)
-            
-    async def _async_get_translation_job(self, job_id: int) -> TranslationResult:
-        """Async version of get_translation_job"""
-        response = await self.client.request("GET", f"/api/v1/translation/translations/{job_id}")
-        return TranslationResult.from_dict(response)