lightly-studio 0.4.6__py3-none-any.whl

lightly_studio/api/routes/video_frames_media.py

@@ -0,0 +1,116 @@
+"""API routes for streaming video frames."""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Generator
+from typing import Any, cast
+from uuid import UUID
+
+import cv2
+import fsspec
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.resolvers import video_frame_resolver
+
+frames_router = APIRouter(prefix="/frames/media", tags=["frames streaming"])
+
+
+ROTATION_MAP: dict[int, Any] = {
+    0: None,
+    90: cv2.ROTATE_90_COUNTERCLOCKWISE,
+    180: cv2.ROTATE_180,
+    270: cv2.ROTATE_90_CLOCKWISE,
+}
+
+
+class FSSpecStreamReader(io.BufferedIOBase):
+    """Wrapper to make fsspec file objects compatible with cv2.VideoCapture's interface."""
+
+    def __init__(self, path: str) -> None:
+        """Initialize the stream reader.
+
+        Args:
+            path: Path to the video file (local path or cloud URL).
+        """
+        self.fs, self.fs_path = fsspec.core.url_to_fs(url=path)
+        self.file = self.fs.open(path=self.fs_path, mode="rb")
+        # Get file size for size() method
+        try:
+            self.file_size = self.file.size
+        except AttributeError:
+            # Fallback: seek to end to get size
+            current_pos = self.file.tell()
+            self.file.seek(0, 2)
+            self.file_size = self.file.tell()
+            self.file.seek(current_pos)
+
+    def read(self, n: int | None = -1) -> bytes:
+        """Read n bytes from the stream."""
+        return cast(bytes, self.file.read(n))
+
+    def read1(self, n: int = -1) -> bytes:
+        """Read up to n bytes from the stream (implementation for BufferedIOBase)."""
+        return cast(bytes, self.file.read(n))
+
+    def seek(self, offset: int, whence: int = 0) -> int:
+        """Seek to the given offset in the stream."""
+        return cast(int, self.file.seek(offset, whence))
+
+    def tell(self) -> int:
+        """Return the current position in the stream."""
+        return cast(int, self.file.tell())
+
+    def size(self) -> int:
+        """Return the total size of the stream."""
+        return cast(int, self.file_size)
+
+    def close(self) -> None:
+        """Close the stream."""
+        if not self.closed:
+            self.file.close()
+            super().close()
+
+    def __enter__(self) -> FSSpecStreamReader:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit the context manager and close the stream."""
+        self.close()
+
+
+@frames_router.get("/{sample_id}")
+async def stream_frame(sample_id: UUID, session: SessionDep) -> StreamingResponse:
+    """Serve a single video frame as PNG using StreamingResponse."""
+    video_frame = video_frame_resolver.get_by_id(session=session, sample_id=sample_id)
+    video_path = video_frame.video.file_path_abs
+
+    # Open video with cv2.VideoCapture using fsspec stream.
+    with FSSpecStreamReader(video_path) as stream:
+        cap = cv2.VideoCapture(cast(Any, stream), apiPreference=cv2.CAP_FFMPEG, params=())
+        if not cap.isOpened():
+            raise HTTPException(400, f"Could not open video: {video_path}")
+        # Seek to the correct frame and read it
+        cap.set(cv2.CAP_PROP_POS_FRAMES, video_frame.frame_number)
+        ret, frame = cap.read()
+        cap.release()
+        if not ret:
+            raise HTTPException(400, f"No frame at index {video_frame.frame_number}")
+
+        # Apply counter-rotation if needed.
+        rotate_code = ROTATION_MAP[video_frame.rotation_deg]
+        if rotate_code is not None:
+            frame = cv2.rotate(src=frame, rotateCode=rotate_code)
+
+        # Encode frame as PNG
+        success, buffer = cv2.imencode(".png", frame)
+        if not success:
+            raise HTTPException(400, f"Could not encode frame: {sample_id}")
+
+        def frame_stream() -> Generator[bytes, None, None]:
+            yield buffer.tobytes()
+
+        return StreamingResponse(frame_stream(), media_type="image/png")

lightly_studio/api/routes/video_media.py

@@ -0,0 +1,223 @@
+"""Video serving endpoint that supports multiple formats."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncGenerator
+
+import fsspec
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+from lightly_studio.api.routes.api import status
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models import video
+
+app_router = APIRouter(prefix="/videos/media")
+
+
+def _parse_range_header(range_header: str | None, file_size: int) -> tuple[int, int] | None:
+    """Parse the Range header and return (start, end) byte positions.
+
+    Args:
+        range_header: The Range header value (e.g., "bytes=0-1023")
+        file_size: The total size of the file in bytes.
+
+    Returns:
+        Tuple of (start, end) byte positions, or None if range is invalid.
+    """
+    if not range_header or not range_header.startswith("bytes="):
+        return None
+
+    try:
+        range_spec = range_header[6:]  # Remove "bytes=" prefix
+        if "-" not in range_spec:
+            return None
+
+        start_str, end_str = range_spec.split("-", 1)
+        start = int(start_str) if start_str else 0
+        end = int(end_str) if end_str else file_size - 1
+
+        # Validate range
+        if start < 0 or end >= file_size or start > end:
+            return None
+
+        return (start, end)
+    except (ValueError, AttributeError):
+        return None
+
+
+async def _stream_file_range(
+    fs: fsspec.AbstractFileSystem,
+    fs_path: str,
+    start: int,
+    end: int,
+    request: Request,
+) -> AsyncGenerator[bytes, None]:
+    """Stream a specific byte range from a file.
+
+    Args:
+        fs: The filesystem instance.
+        fs_path: The path to the file.
+        start: Start byte position.
+        end: End byte position.
+        request: FastAPI request object for disconnect detection.
+    """
+    content_length = end - start + 1
+    chunk_size = 1024 * 1024  # 1MB chunks
+
+    try:
+        with fs.open(fs_path, "rb") as f:
+            f.seek(start)
+            remaining = content_length
+
+            while remaining > 0:
+                # Check if client disconnected
+                if await request.is_disconnected():
+                    break
+
+                read_size = min(chunk_size, remaining)
+                chunk = f.read(read_size)
+                if not chunk:
+                    break
+                yield chunk
+                remaining -= len(chunk)
+    except Exception:
+        # Handle file read errors gracefully
+        pass
+
+
+async def _stream_full_file(
+    fs: fsspec.AbstractFileSystem,
+    fs_path: str,
+    request: Request,
+) -> AsyncGenerator[bytes, None]:
+    """Stream the entire file.
+
+    Args:
+        fs: The filesystem instance.
+        fs_path: The path to the file.
+        request: FastAPI request object for disconnect detection.
+    """
+    chunk_size = 1024 * 1024  # 1MB chunks
+
+    try:
+        with fs.open(fs_path, "rb") as f:
+            while True:
+                # Check if client disconnected
+                if await request.is_disconnected():
+                    break
+
+                chunk = f.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+    except Exception:
+        # Handle file read errors gracefully
+        pass
+
+
+@app_router.get("/{sample_id}")
+async def serve_video_by_sample_id(
+    sample_id: str,
+    session: SessionDep,
+    request: Request,
+    range_header: str | None = Header(None, alias="range"),
+) -> StreamingResponse:
+    """Serve a video by sample ID with HTTP Range request support.
+
+    This endpoint supports HTTP Range requests, which are essential for
+    efficient video streaming. Browsers use Range requests to:
+    - Load only the necessary byte ranges
+    - Enable seeking without downloading the entire file
+    - Support multiple concurrent requests
+
+    Args:
+        sample_id: The ID of the video sample.
+        session: Database session dependency (closed when function returns, before streaming).
+        request: FastAPI request object.
+        range_header: The HTTP Range header value.
+
+    Returns:
+        StreamingResponse with the video data, supporting partial content.
+    """
+    # Get sample record and close session early to avoid blocking
+    sample_record = session.get(video.VideoTable, sample_id)
+    if not sample_record:
+        raise HTTPException(
+            status_code=status.HTTP_STATUS_NOT_FOUND,
+            detail=f"Video sample not found: {sample_id}",
+        )
+
+    file_path = sample_record.file_path_abs
+    content_type = _get_content_type(file_path)
+
+    # Extract file_path (a string) before returning StreamingResponse.
+    # FastAPI's dependency system will close the session when this function returns,
+    # which happens immediately after creating the StreamingResponse (before streaming starts).
+    # This ensures the DB connection isn't held during the async streaming operation.
+
+    try:
+        fs, fs_path = fsspec.core.url_to_fs(file_path)
+        file_size = fs.size(fs_path)
+
+        # Parse range header if present
+        range_tuple = _parse_range_header(range_header, file_size)
+
+        if range_tuple:
+            # Partial content request
+            start, end = range_tuple
+            content_length = end - start + 1
+
+            return StreamingResponse(
+                _stream_file_range(fs, fs_path, start, end, request),
+                status_code=206,  # Partial Content
+                media_type=content_type,
+                headers={
+                    "Accept-Ranges": "bytes",
+                    "Content-Range": f"bytes {start}-{end}/{file_size}",
+                    "Content-Length": str(content_length),
+                    "Cache-Control": "public, max-age=3600",
+                },
+            )
+
+        # Full file request
+        return StreamingResponse(
+            _stream_full_file(fs, fs_path, request),
+            media_type=content_type,
+            headers={
+                "Accept-Ranges": "bytes",
+                "Content-Length": str(file_size),
+                "Cache-Control": "public, max-age=3600",
+            },
+        )
+    except FileNotFoundError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_STATUS_NOT_FOUND,
+            detail=f"File not found: {file_path}",
+        ) from exc
+    except OSError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_STATUS_NOT_FOUND,
+            detail=f"Error accessing file {file_path}: {exc.strerror}",
+        ) from exc
+
+
+def _get_content_type(file_path: str) -> str:
+    """Get the appropriate content type for a video file based on its extension."""
+    ext = os.path.splitext(file_path)[1].lower()
+    content_types = {
+        ".mp4": "video/mp4",
+        ".mov": "video/quicktime",
+        ".avi": "video/x-msvideo",
+        ".mkv": "video/x-matroska",
+        ".webm": "video/webm",
+        ".flv": "video/x-flv",
+        ".wmv": "video/x-ms-wmv",
+        ".mpeg": "video/mpeg",
+        ".mpg": "video/mpeg",
+        ".3gp": "video/3gpp",
+        ".ts": "video/mp2t",
+        ".m4v": "video/x-m4v",
+    }
+    return content_types.get(ext, "application/octet-stream")

lightly_studio/api/routes/webapp.py

@@ -0,0 +1,51 @@
+"""This module contains the API routes for managing datasets."""
+
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from .api.status import HTTP_STATUS_NOT_FOUND
+
+app_router = APIRouter()
+
+# Get the current project root directory
+project_root = Path(__file__).resolve().parent.parent.parent
+
+webapp_dir = project_root / "dist_lightly_studio_view_app"
+
+# Check if the webapp directory exists and raise an error if it doesn't
+if not webapp_dir.exists():
+    raise RuntimeError(f"Directory '{webapp_dir}' does not exist in '{project_root}'")
+
+# Ensure the path is absolute
+webapp_dir = webapp_dir.resolve()
+
+# ensure the webapp index.html file exists
+index_file = webapp_dir / "index.html"
+if not index_file.exists():
+    raise RuntimeError("No index file. Did you forget to build the webapp?")
+
+
+@app_router.get("/{path:path}", include_in_schema=False)
+async def serve_static_webapp_files_or_default_index_file(
+    path: str,
+) -> FileResponse:
+    """Serve static files of webapp or serve the index.html file.
+
+    Try to serve static files with file extensions or return 404.
+    If no file extension, return the main webapp index.html.
+    """
+    file_path = webapp_dir / path
+
+    # if file has an extension, try to return the file
+    if file_path.suffix:
+        if not file_path.exists() or not file_path.is_file():
+            raise HTTPException(
+                status_code=HTTP_STATUS_NOT_FOUND,
+                detail=f"File '{path}' not found",
+            )
+        return FileResponse(file_path)
+
+    # if file has no extension, return the index.html file regardless of path
+    return FileResponse(index_file)

lightly_studio/api/server.py

@@ -0,0 +1,94 @@
+"""This module contains the Server class for running the API using Uvicorn."""
+
+import random
+import socket
+
+import uvicorn
+
+from lightly_studio.api.app import app
+from lightly_studio.dataset import env
+
+
+class Server:
+    """This class represents a server for running the API using Uvicorn."""
+
+    port: int
+    host: str
+
+    def __init__(self, host: str, port: int) -> None:
+        """Initialize the Server with host and port.
+
+        Args:
+            host (str): The hostname to bind the server to.
+            port (int): The port number to run the server on.
+        """
+        self.host = host
+        self.port = _get_available_port(host=host, preferred_port=port)
+        if port != self.port:
+            env.LIGHTLY_STUDIO_PORT = self.port
+            env.APP_URL = f"{env.LIGHTLY_STUDIO_PROTOCOL}://{env.LIGHTLY_STUDIO_HOST}:{env.LIGHTLY_STUDIO_PORT}"
+
+    def start(self) -> None:
+        """Start the API server using Uvicorn."""
+        # start the app with connection limits and timeouts
+        uvicorn.run(
+            app,
+            host=self.host,
+            port=self.port,
+            http="h11",
+            # https://uvicorn.dev/settings/#resource-limits
+            limit_concurrency=100,  # Max concurrent connections
+            limit_max_requests=10000,  # Max requests before worker restart
+            # https://uvicorn.dev/settings/#timeouts
+            timeout_keep_alive=5,  # Keep-alive timeout in seconds
+            timeout_graceful_shutdown=30,  # Graceful shutdown timeout
+            access_log=env.LIGHTLY_STUDIO_DEBUG,
+        )
+
+
+def _get_available_port(host: str, preferred_port: int, max_tries: int = 50) -> int:
+    """Get an available port, if possible, otherwise a random one.
+
+    Args:
+        host: The hostname or IP address to bind to.
+        preferred_port: The port to try first.
+        max_tries: Maximum number of random ports to try.
+
+    Raises:
+        RuntimeError if it cannot find an available port.
+
+    Returns:
+        An available port number.
+    """
+    if _is_port_available(host=host, port=preferred_port):
+        return preferred_port
+
+    # Try random ports in the range 1024-65535
+    for _ in range(max_tries):
+        port = random.randint(1024, 65535)
+        if _is_port_available(host=host, port=port):
+            return port
+
+    raise RuntimeError("Could not find an available port.")
+
+
+def _is_port_available(host: str, port: int) -> bool:
+    # Determine address family based on host.
+    try:
+        socket.inet_pton(socket.AF_INET, host)
+        families = [socket.AF_INET]
+    except OSError:
+        try:
+            socket.inet_pton(socket.AF_INET6, host)
+            families = [socket.AF_INET6]
+        except OSError:
+            # Fallback for hostnames like 'localhost'
+            families = [socket.AF_INET, socket.AF_INET6]
+
+    for family in families:
+        with socket.socket(family, socket.SOCK_STREAM) as s:
+            try:
+                s.bind((host, port))
+            except OSError:
+                return False
+    return True