synapse-sdk 1.0.0a35__py3-none-any.whl → 2025.11.7__py3-none-any.whl

synapse_sdk/utils/file/video/transcode.py

@@ -0,0 +1,307 @@
+import asyncio
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+import ffmpeg
+
+
+# Exception classes
+class VideoTranscodeError(Exception):
+    """Base exception for video transcoding errors."""
+
+    pass
+
+
+class UnsupportedFormatError(VideoTranscodeError):
+    """Raised when input format is not supported."""
+
+    pass
+
+
+class FFmpegNotFoundError(VideoTranscodeError):
+    """Raised when FFmpeg is not installed or not in PATH."""
+
+    pass
+
+
+class TranscodingFailedError(VideoTranscodeError):
+    """Raised when FFmpeg transcoding process fails."""
+
+    pass
+
+
+@dataclass
+class TranscodeConfig:
+    """Video transcoding configuration."""
+
+    vcodec: str = 'libx264'  # Video codec
+    preset: str = 'medium'  # Encoding preset (ultrafast to veryslow)
+    crf: int = 28  # Constant Rate Factor (0-51, lower=better quality)
+    acodec: str = 'aac'  # Audio codec
+    audio_bitrate: str = '128k'  # Audio bitrate
+    movflags: str = '+faststart'  # MP4 optimization flags
+    resolution: Optional[str] = None  # Target resolution (e.g., '1920x1080')
+    fps: Optional[int] = None  # Target frame rate
+    start_time: Optional[float] = None  # Trim start time in seconds
+    duration: Optional[float] = None  # Trim duration in seconds
+
+
+# Supported input formats
+SUPPORTED_FORMATS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv', '.wmv', '.mpeg', '.mpg', '.m4v', '.3gp', '.ogv'}
+
+
+def _check_ffmpeg_available():
+    """Check if FFmpeg is available in PATH."""
+    if not shutil.which('ffmpeg'):
+        raise FFmpegNotFoundError(
+            'FFmpeg is not installed or not found in PATH. Please install FFmpeg to use video transcoding features.'
+        )
+
+
+def validate_video_format(video_path: str | Path) -> bool:
+    """
+    Check if video format is supported for transcoding.
+
+    Args:
+        video_path (str | Path): Path to the video file
+
+    Returns:
+        bool: True if format is supported, False otherwise
+    """
+    path = Path(video_path)
+    return path.suffix.lower() in SUPPORTED_FORMATS
+
+
+def get_video_info(video_path: str | Path) -> dict:
+    """
+    Extract video metadata (resolution, duration, codecs, etc.).
+
+    Args:
+        video_path (str | Path): Path to the video file
+
+    Returns:
+        dict: Video metadata information
+
+    Raises:
+        VideoTranscodeError: If unable to probe video file
+    """
+    _check_ffmpeg_available()
+
+    try:
+        probe = ffmpeg.probe(str(video_path))
+
+        video_info = {}
+
+        # Get format information
+        if 'format' in probe:
+            format_info = probe['format']
+            video_info['duration'] = float(format_info.get('duration', 0))
+            video_info['size'] = int(format_info.get('size', 0))
+            video_info['bitrate'] = int(format_info.get('bit_rate', 0))
+
+        # Get stream information
+        video_streams = [stream for stream in probe['streams'] if stream['codec_type'] == 'video']
+        audio_streams = [stream for stream in probe['streams'] if stream['codec_type'] == 'audio']
+
+        if video_streams:
+            video_stream = video_streams[0]
+            video_info['width'] = int(video_stream.get('width', 0))
+            video_info['height'] = int(video_stream.get('height', 0))
+            video_info['video_codec'] = video_stream.get('codec_name', '')
+            video_info['fps'] = eval(video_stream.get('r_frame_rate', '0/1'))
+
+        if audio_streams:
+            audio_stream = audio_streams[0]
+            video_info['audio_codec'] = audio_stream.get('codec_name', '')
+            video_info['channels'] = int(audio_stream.get('channels', 0))
+            video_info['sample_rate'] = int(audio_stream.get('sample_rate', 0))
+
+        return video_info
+
+    except Exception as e:
+        raise VideoTranscodeError(f'Failed to probe video file: {str(e)}')
+
+
+def _build_ffmpeg_stream(input_path: str | Path, output_path: str | Path, config: TranscodeConfig):
+    """Build FFmpeg stream with configuration."""
+    stream = ffmpeg.input(str(input_path))
+
+    # Apply start time and duration trimming
+    if config.start_time is not None or config.duration is not None:
+        kwargs = {}
+        if config.start_time is not None:
+            kwargs['ss'] = config.start_time
+        if config.duration is not None:
+            kwargs['t'] = config.duration
+        stream = ffmpeg.input(str(input_path), **kwargs)
+
+    # Apply video filters
+    if config.resolution or config.fps:
+        if config.resolution:
+            width, height = config.resolution.split('x')
+            stream = ffmpeg.filter(stream, 'scale', width, height)
+        if config.fps:
+            stream = ffmpeg.filter(stream, 'fps', fps=config.fps)
+
+    # Build output with encoding parameters
+    output_kwargs = {
+        'vcodec': config.vcodec,
+        'preset': config.preset,
+        'crf': config.crf,
+        'acodec': config.acodec,
+        'audio_bitrate': config.audio_bitrate,
+        'movflags': config.movflags,
+    }
+
+    return ffmpeg.output(stream, str(output_path), **output_kwargs)
+
+
+def transcode_video(
+    input_path: str | Path,
+    output_path: str | Path,
+    config: Optional[TranscodeConfig] = None,
+    progress_callback: Optional[Callable[[float], None]] = None,
+) -> Path:
+    """
+    Transcode video with specified configuration.
+
+    Args:
+        input_path (str | Path): Path to input video file
+        output_path (str | Path): Path to output video file
+        config (Optional[TranscodeConfig]): Transcoding configuration
+        progress_callback (Optional[Callable[[float], None]]): Progress callback function
+
+    Returns:
+        Path: Path to the transcoded video file
+
+    Raises:
+        UnsupportedFormatError: If input format is not supported
+        FFmpegNotFoundError: If FFmpeg is not available
+        TranscodingFailedError: If transcoding fails
+    """
+    _check_ffmpeg_available()
+
+    input_path = Path(input_path)
+    output_path = Path(output_path)
+
+    if not validate_video_format(input_path):
+        raise UnsupportedFormatError(f'Unsupported video format: {input_path.suffix}')
+
+    if config is None:
+        config = TranscodeConfig()
+
+    # Ensure output directory exists
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Build FFmpeg command
+        stream = _build_ffmpeg_stream(input_path, output_path, config)
+
+        # Run FFmpeg
+        if progress_callback:
+            # Get video duration for progress calculation
+            video_info = get_video_info(input_path)
+            total_duration = video_info.get('duration', 0)
+
+            # Run with progress monitoring
+            process = ffmpeg.run_async(stream, pipe_stderr=True, overwrite_output=True)
+
+            while True:
+                output = process.stderr.readline()
+                if output == b'' and process.poll() is not None:
+                    break
+                if output:
+                    line = output.decode('utf-8')
+                    # Parse progress from FFmpeg output
+                    if 'time=' in line and total_duration > 0:
+                        try:
+                            time_str = line.split('time=')[1].split()[0]
+                            hours, minutes, seconds = time_str.split(':')
+                            current_time = int(hours) * 3600 + int(minutes) * 60 + float(seconds)
+                            progress = min(current_time / total_duration, 1.0)
+                            progress_callback(progress)
+                        except (ValueError, IndexError):
+                            pass
+
+            if process.returncode != 0:
+                raise TranscodingFailedError('FFmpeg process failed')
+        else:
+            # Run without progress monitoring
+            ffmpeg.run(stream, overwrite_output=True, quiet=True)
+
+        return output_path
+
+    except ffmpeg.Error as e:
+        error_message = e.stderr.decode('utf-8') if e.stderr else str(e)
+        raise TranscodingFailedError(f'Transcoding failed: {error_message}')
+    except Exception as e:
+        raise VideoTranscodeError(f'Unexpected error during transcoding: {str(e)}')
+
+
+def optimize_for_web(video_path: str | Path, output_path: str | Path) -> Path:
+    """
+    Quick optimization for web streaming with default settings.
+
+    Args:
+        video_path (str | Path): Path to input video file
+        output_path (str | Path): Path to output video file
+
+    Returns:
+        Path: Path to the optimized video file
+    """
+    config = TranscodeConfig(
+        preset='fast',  # Faster encoding for web optimization
+        crf=23,  # Better quality for web
+        movflags='+faststart+frag_keyframe+empty_moov',  # Advanced web optimization
+    )
+    return transcode_video(video_path, output_path, config)
+
+
+async def atranscode_video(
+    input_path: str | Path, output_path: str | Path, config: Optional[TranscodeConfig] = None
+) -> Path:
+    """
+    Async version of transcode_video.
+
+    Args:
+        input_path (str | Path): Path to input video file
+        output_path (str | Path): Path to output video file
+        config (Optional[TranscodeConfig]): Transcoding configuration
+
+    Returns:
+        Path: Path to the transcoded video file
+    """
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, transcode_video, input_path, output_path, config)
+
+
+def transcode_batch(
+    video_paths: list[Path], output_dir: Path, config: Optional[TranscodeConfig] = None, max_workers: int = 4
+) -> list[Path]:
+    """
+    Process multiple videos concurrently.
+
+    Args:
+        video_paths (list[Path]): List of input video file paths
+        output_dir (Path): Directory for output files
+        config (Optional[TranscodeConfig]): Transcoding configuration
+        max_workers (int): Maximum number of concurrent workers
+
+    Returns:
+        list[Path]: List of paths to transcoded video files
+    """
+    import concurrent.futures
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    def process_video(video_path):
+        output_path = output_dir / f'{video_path.stem}_transcoded.mp4'
+        return transcode_video(video_path, output_path, config)
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+        results = list(executor.map(process_video, video_paths))
+
+    return results

synapse_sdk/utils/{file.py → file.py.backup}

@@ -7,6 +7,7 @@ import operator
 import zipfile
 from functools import reduce
 from pathlib import Path
+from typing import IO, Any, Callable
 
 import aiohttp
 import requests
@@ -16,6 +17,39 @@ from synapse_sdk.utils.network import clean_url
 from synapse_sdk.utils.string import hash_text
 
 
+def read_file_in_chunks(file_path, chunk_size=1024 * 1024 * 50):
+    """
+    Read a file in chunks for efficient memory usage during file processing.
+
+    This function is particularly useful for large files or when you need to process
+    files in chunks, such as for uploading or hashing.
+
+    Args:
+        file_path (str | Path): Path to the file to read
+        chunk_size (int, optional): Size of each chunk in bytes. Defaults to 50MB (1024 * 1024 * 50)
+
+    Yields:
+        bytes: File content chunks
+
+    Raises:
+        FileNotFoundError: If the file doesn't exist
+        PermissionError: If the file can't be read due to permissions
+        OSError: If there's an OS-level error reading the file
+
+    Example:
+        ```python
+        from synapse_sdk.utils.file import read_file_in_chunks
+
+        # Read a file in 10MB chunks
+        for chunk in read_file_in_chunks('large_file.bin', chunk_size=1024*1024*10):
+            process_chunk(chunk)
+        ```
+    """
+    with open(file_path, 'rb') as file:
+        while chunk := file.read(chunk_size):
+            yield chunk
+
+
 def download_file(url, path_download, name=None, coerce=None, use_cached=True):
     chunk_size = 1024 * 1024 * 50
     cleaned_url = clean_url(url)  # remove query params and fragment
@@ -150,11 +184,55 @@ def calculate_checksum(file_path, prefix=''):
     return checksum
 
 
-def archive(input_path, output_path):
+def get_checksum_from_file(file: IO[Any], digest_mod: Callable[[], Any] = hashlib.sha1) -> str:
+    """
+    Calculate checksum for a file-like object.
+
+    Args:
+        file (IO[Any]): File-like object with read() method that supports reading in chunks
+        digest_mod (Callable[[], Any]): Hash algorithm from hashlib (defaults to hashlib.sha1)
+
+    Returns:
+        str: Hexadecimal digest of the file contents
+
+    Example:
+        ```python
+        import hashlib
+        from io import BytesIO
+        from synapse_sdk.utils.file import get_checksum_from_file
+
+        # With BytesIO
+        data = BytesIO(b'Hello, world!')
+        checksum = get_checksum_from_file(data)
+
+        # With different hash algorithm
+        checksum = get_checksum_from_file(data, digest_mod=hashlib.sha256)
+        ```
+    """
+    digest = digest_mod()
+    chunk_size = 4096
+
+    # Reset file pointer to beginning if possible
+    if hasattr(file, 'seek'):
+        file.seek(0)
+
+    while True:
+        chunk = file.read(chunk_size)
+        if not chunk:
+            break
+        if isinstance(chunk, str):
+            chunk = chunk.encode('utf-8')
+        digest.update(chunk)
+
+    return digest.hexdigest()
+
+
+def archive(input_path, output_path, append=False):
     input_path = Path(input_path)
     output_path = Path(output_path)
 
-    with zipfile.ZipFile(output_path, mode='w', compression=zipfile.ZIP_DEFLATED) as zipf:
+    mode = 'a' if append and output_path.exists() else 'w'
+    with zipfile.ZipFile(output_path, mode=mode, compression=zipfile.ZIP_DEFLATED) as zipf:
         if input_path.is_file():
             zipf.write(input_path, input_path.name)
         else:
@@ -196,6 +274,10 @@ def convert_file_to_base64(file_path):
     Returns:
         str: Base64 encoded string of the file contents
     """
+    # FIXME base64 is sent sometimes.
+    if file_path.startswith('data:'):
+        return file_path
+
     # Convert string path to Path object
     path = Path(file_path)
 

synapse_sdk/utils/http.py

@@ -0,0 +1,138 @@
+import logging
+import os
+import tempfile
+import threading
+import time
+import uuid
+from contextlib import contextmanager
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+
+import requests
+
+from synapse_sdk.utils.network import get_available_ports_host
+
+
+class SingleFileHttpServer(SimpleHTTPRequestHandler):
+    """
+    Custom HTTP request handler that serves a single specified file
+    regardless of the request path.
+    """
+
+    def __init__(self, *args, file_path=None, content_type=None, random_path=None, **kwargs):
+        self.file_path = file_path
+        self.content_type = content_type
+        self.random_path = random_path
+        super().__init__(*args, **kwargs)
+
+    def do_GET(self):
+        """Handle GET requests by serving the single file."""
+        try:
+            # Check if the path matches our random path
+            if self.random_path and self.path == f'/{self.random_path}':
+                self.send_response(200)
+                if self.content_type:
+                    self.send_header('Content-type', self.content_type)
+                self.send_header('Content-Length', str(os.path.getsize(self.file_path)))
+                self.end_headers()
+
+                with open(self.file_path, 'rb') as file:
+                    self.wfile.write(file.read())
+            elif self.path == '/':
+                # Redirect root to the random path
+                self.send_response(302)
+                self.send_header('Location', f'/{self.random_path}')
+                self.end_headers()
+            else:
+                self.send_error(404, 'File not found')
+
+        except Exception as e:
+            self.send_error(500, str(e))
+
+
+@contextmanager
+def temp_file_server(image=None, file_path=None, format='JPEG', host='0.0.0.0', port=None, content_type=None):
+    """
+    Context manager that serves a file temporarily via HTTP.
+
+    Args:
+        image: A PIL Image object to serve (optional)
+        file_path: Path to an existing file to serve (optional - used if image not provided)
+        format: Image format when saving a PIL Image (default: "JPEG")
+        host: Host to serve on (default: "0.0.0.0")
+        port: Port to serve on (default: auto-selected free port)
+        content_type: Content type header (default: auto-detected based on format)
+
+    Returns:
+        URL where the file is being served
+
+    Usage:
+        with temp_file_serve(image=my_pillow_img) as url:
+            # use url to access the image
+            print(f"Image available at: {url}")
+    """
+    if image is None and file_path is None:
+        raise ValueError('Either image or file_path must be provided')
+
+    # Use a free port if none specified
+    if port is None:
+        port = get_available_ports_host(start_port=8991, end_port=8999)
+
+    temp_dir = None
+    temp_file_path = None
+
+    try:
+        random_filename = f'{uuid.uuid4().hex}'
+
+        if image is not None:
+            temp_dir = tempfile.mkdtemp()
+            ext_map = {'JPEG': '.jpg', 'PNG': '.png', 'GIF': '.gif', 'WEBP': '.webp'}
+            content_type_map = {'JPEG': 'image/jpeg', 'PNG': 'image/png', 'GIF': 'image/gif', 'WEBP': 'image/webp'}
+
+            ext = ext_map.get(format, '.jpg')
+            if content_type is None:
+                content_type = content_type_map.get(format, 'image/jpeg')
+
+            temp_file_path = os.path.join(temp_dir, f'temp_image{ext}')
+            image.save(temp_file_path, format=format)
+            file_path = temp_file_path
+            random_filename += ext
+        else:
+            _, ext = os.path.splitext(file_path)
+            random_filename += ext
+
+        def handler(*args, **kwargs):
+            return SingleFileHttpServer(
+                *args, file_path=file_path, content_type=content_type, random_path=random_filename, **kwargs
+            )
+
+        server = HTTPServer((host, port), handler)
+
+        server_thread = threading.Thread(target=server.serve_forever)
+        server_thread.daemon = True
+        server_thread.start()
+
+        url = f'http://localhost:{port}/{random_filename}'
+
+        while True:
+            try:
+                response = requests.get(url)
+                if response.status_code == 200:
+                    break
+            except requests.exceptions.ConnectionError:
+                pass
+            time.sleep(0.01)
+
+        try:
+            yield url
+        finally:
+            server.shutdown()
+            server.server_close()
+
+    finally:
+        if temp_dir:
+            try:
+                if temp_file_path and os.path.exists(temp_file_path):
+                    os.unlink(temp_file_path)
+                os.rmdir(temp_dir)
+            except Exception as e:
+                logging.warning(f'Error cleaning up temporary files: {e}')