feat: update capture binary support and add session export

- Rename recorder references to capture in CaptureClient
- Bump videodb-capture-bin dependency to >=0.2.8
- Add channels, export_status, exported_videos to CaptureSession
- Add displays property and export() method to CaptureSession
- Fix generate_clip docstring return type to SearchResult
- Bump version to 0.4.1

Author: lalit-videodb

setup.py

@@ -39,7 +39,7 @@
         "websockets>=11.0.3",
     ],
     extras_require={
-        "capture": ["videodb-capture-bin>=0.2.7"],
+        "capture": ["videodb-capture-bin>=0.2.8"],
     },
     classifiers=[
         "Intended Audience :: Developers",

videodb/__about__.py

@@ -2,7 +2,7 @@
 
 
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 __title__ = "videodb"
 __author__ = "videodb"
 __email__ = "contact@videodb.io"

videodb/capture.py

@@ -9,9 +9,9 @@
 
 logger = logging.getLogger(__name__)
 
-def get_recorder_path():
+def get_capture_binary_path():
     """
-    Attempts to find the path to the recorder binary.
+    Attempts to find the path to the capture binary.
     If the optional 'videodb-capture-bin' package is not installed,
     it raises a RuntimeError with instructions.
     """
@@ -21,13 +21,13 @@ def get_recorder_path():
     except ImportError:
         error_msg = (
             "Capture runtime not found.\n"
-            "To use recording features, please install the capture dependencies:\n"
+            "To use capture features, please install the capture dependencies:\n"
             "pip install 'videodb[capture]'"
         )
         logger.error(error_msg)
         raise RuntimeError(error_msg)
     except Exception as e:
-        logger.error(f"Failed to resolve recorder path: {e}")
+        logger.error(f"Failed to resolve capture binary path: {e}")
         raise
 
 
@@ -167,14 +167,14 @@ def __init__(
         self._session_id: Optional[str] = None
         self._proc = None
         self._futures: Dict[str, asyncio.Future] = {}
-        self._binary_path = get_recorder_path()
+        self._binary_path = get_capture_binary_path()
         self._event_queue = asyncio.Queue()
 
     def __repr__(self) -> str:
         return f"CaptureClient(base_url={self.base_url})"
 
     async def _ensure_process(self):
-        """Ensure the recorder binary is running."""
+        """Ensure the capture binary is running."""
         if self._proc is not None and self._proc.returncode is None:
             return
 
@@ -194,7 +194,7 @@ async def _ensure_process(self):
     async def _send_command(
         self, command: str, params: Optional[Dict[str, Any]] = None
     ) -> Dict[str, Any]:
-        """Send a command to the recorder binary and await response.
+        """Send a command to the capture binary and await response.
 
         :param str command: Command name.
         :param dict params: Command parameters.
@@ -210,7 +210,7 @@ async def _send_command(
             "params": params or {},
         }
 
-        # Framing: videodb_recorder|<JSON>\n
+        # IPC protocol framing: videodb_recorder|<JSON>\n
         message = f"videodb_recorder|{json.dumps(payload)}\n"
         self._proc.stdin.write(message.encode("utf-8"))
         await self._proc.stdin.drain()
@@ -254,18 +254,18 @@ async def _read_stdout_loop(self):
                     await self._event_queue.put(data)
 
             except Exception as e:
-                logger.error(f"Failed to parse recorder message: {e}")
+                logger.error(f"Failed to parse capture message: {e}")
 
     async def _read_stderr_loop(self):
         """Loop to read stderr and log messages."""
         while True:
             line = await self._proc.stderr.readline()
             if not line:
                 break
-            logger.debug(f"[Recorder Binary]: {line.decode('utf-8', errors='replace').strip()}")
+            logger.debug(f"[Capture Binary]: {line.decode('utf-8', errors='replace').strip()}")
 
     async def shutdown(self):
-        """Cleanly terminate the recorder binary process."""
+        """Cleanly terminate the capture binary process."""
         if self._proc:
             try:
                 # Try graceful shutdown command first
@@ -392,7 +392,7 @@ async def stop_session(self) -> None:
         await self._send_command("stopRecording", {"sessionId": self._session_id})
 
     async def events(self):
-        """Async generator that yields events from the recorder."""
+        """Async generator that yields events from the capture binary."""
         while True:
             try:
                 # Use a timeout so we can check if the process is still alive

videodb/capture_session.py

@@ -1,4 +1,5 @@
-from typing import List
+from typing import List, Optional
+from videodb._constants import ApiPath
 from videodb.rtstream import RTStream
 
 
@@ -10,6 +11,10 @@ class CaptureSession:
     :ivar str end_user_id: ID of the end user
     :ivar str client_id: Client-provided session ID
     :ivar str status: Current status of the session
+    :ivar list channels: List of channel dicts with id, name, type, is_primary
+    :ivar str primary_video_channel_id: Channel ID of the primary video source
+    :ivar str export_status: Current export status (exporting, exported, failed)
+    :ivar dict exported_videos: Mapping of channel_id to exported video_id
     """
 
     def __init__(self, _connection, id: str, collection_id: str, **kwargs) -> None:
@@ -35,6 +40,10 @@ def _update_attributes(self, data: dict) -> None:
         self.callback_url = data.get("callback_url")
         self.exported_video_id = data.get("exported_video_id")
         self.metadata = data.get("metadata", {})
+        self.channels = data.get("channels", [])
+        self.primary_video_channel_id = data.get("primary_video_channel_id")
+        self.export_status = data.get("export_status")
+        self.exported_videos = data.get("exported_videos", {})
 
         self.rtstreams = []
         for rts_data in data.get("rtstreams", []):
@@ -43,6 +52,15 @@ def _update_attributes(self, data: dict) -> None:
             stream = RTStream(self._connection, **rts_data)
             self.rtstreams.append(stream)
 
+    @property
+    def displays(self) -> list:
+        """Video channels in the session.
+
+        :return: List of channel dicts where type is 'video'
+        :rtype: list[dict]
+        """
+        return [ch for ch in self.channels if ch.get("type") == "video"]
+
     def get_rtstream(self, category: str) -> List[RTStream]:
         """Get list of RTStreams by category.
 
@@ -59,3 +77,24 @@ def get_rtstream(self, category: str) -> List[RTStream]:
                 filtered_streams.append(stream)
 
         return filtered_streams
+
+    def export(self, video_channel_id: Optional[str] = None) -> dict:
+        """Trigger export for this capture session.
+
+        Returns the existing video_id immediately if the channel was already
+        exported. Otherwise starts an async export and returns.
+
+        :param str video_channel_id: Optional channel ID of the video to export.
+            Defaults to the primary video channel.
+        :return: Export response with session_id, video_channel_id, and
+            video_id (if already exported)
+        :rtype: dict
+        """
+        data = {}
+        if video_channel_id:
+            data["video_channel_id"] = video_channel_id
+
+        return self._connection.post(
+            path=f"{ApiPath.collection}/{self.collection_id}/{ApiPath.capture}/{ApiPath.session}/{self.id}/{ApiPath.export}",
+            data=data,
+        )

videodb/video.py

@@ -707,10 +707,10 @@ def clip(
         ) -> str:
             """Generate a clip from the video using a prompt.
             :param str prompt: Prompt to generate the clip
-            :param str content_type: Content type for the clip
-            :param str model_name: Model name for generation
-            :return: The stream url of the generated clip
-            :rtype: str
+            :param str content_type: Content type for the clip. Valid options: "spoken", "visual", "multimodal"
+            :param str model_name: Model tier for generation. Valid options: "basic", "pro", "ultra"
+            :return: The search result of the generated clip
+            :rtype: :class:`SearchResult <SearchResult>`
             """
 
             clip_data = self._connection.post(