patch bump

CHANGELOG.md

@@ -5,12 +5,13 @@ All notable changes to this project 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).
 
-# [0.23.0] - 2026-01-09
+# [0.24.0] - 2026-01-09
 
 ### Added
 
 -   new subcommands added to input, see [Input](https://github.com/onyx-and-iris/obsws-cli?tab=readme-ov-file#input)
 -   settings command group, see [Settings](https://github.com/onyx-and-iris/obsws-cli?tab=readme-ov-file#settings)
+-   media command group, see [Media](https://github.com/onyx-and-iris/obsws-cli?tab=readme-ov-file#media)
 
 
 # [0.20.0] - 2025-07-14

README.md

@@ -776,6 +776,44 @@ obsws-cli settings video
 obsws-cli settings video --base-width=1920 --base-height=1080
 ```
 
+#### Media
+
+-   cursor: Get/set the cursor position of a media input.
+    -   args: InputName
+
+        *optional*
+        -   TimeString
+
+```console
+obsws-cli media cursor "Media"
+
+obsws-cli media cursor "Media" "00:08:30"
+```
+
+-   play: Plays a media input.
+
+```console
+obsws-cli media play "Media"
+```
+
+-   pause: Pauses a media input.
+
+```console
+obsws-cli media pause "Media"
+```
+
+-   stop: Stops a media input.
+
+```console
+obsws-cli media stop "Media"
+```
+
+-   restart: Restarts a media input.
+
+```console
+obsws-cli media restart "Media"
+```
+
 
 ## License
 

obsws_cli/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present onyx-and-iris <code@onyxandiris.online>
 #
 # SPDX-License-Identifier: MIT
-__version__ = '0.23.0'
+__version__ = '0.24.1'

obsws_cli/app.py

@@ -18,10 +18,12 @@ for sub_typer in (
     'group',
     'hotkey',
     'input',
+    'media',
     'profile',
     'projector',
     'record',
     'replaybuffer',
+    'settings',
     'scene',
     'scenecollection',
     'sceneitem',
@@ -30,7 +32,6 @@ for sub_typer in (
     'studiomode',
     'text',
     'virtualcam',
-    'settings',
 ):
     module = importlib.import_module(f'.{sub_typer}', package=__package__)
     app.add_typer(module.app, name=sub_typer)

obsws_cli/group.py

@@ -26,6 +26,7 @@ def list_(
         typer.Argument(
             show_default='The current scene',
             help='Scene name to list groups for',
+            callback=validate.scene_in_scenes,
         ),
     ] = None,
 ):
@@ -33,10 +34,6 @@ def list_(
     if not scene_name:
         scene_name = ctx.obj['obsws'].get_current_program_scene().scene_name
 
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f"Scene '{scene_name}' not found.")
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_scene_item_list(scene_name)
     groups = [
         (item.get('sceneItemId'), item.get('sourceName'), item.get('sceneItemEnabled'))
@@ -92,17 +89,18 @@ def show(
     ctx: typer.Context,
     scene_name: Annotated[
         str,
-        typer.Argument(..., show_default=False, help='Scene name the group is in'),
+        typer.Argument(
+            ...,
+            show_default=False,
+            help='Scene name the group is in',
+            callback=validate.scene_in_scenes,
+        ),
     ],
     group_name: Annotated[
         str, typer.Argument(..., show_default=False, help='Group name to show')
     ],
 ):
     """Show a group in a scene."""
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f"Scene '{scene_name}' not found.")
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_scene_item_list(scene_name)
     if (group := _get_group(group_name, resp)) is None:
         console.err.print(
@@ -123,17 +121,19 @@ def show(
 def hide(
     ctx: typer.Context,
     scene_name: Annotated[
-        str, typer.Argument(..., show_default=False, help='Scene name the group is in')
+        str,
+        typer.Argument(
+            ...,
+            show_default=False,
+            help='Scene name the group is in',
+            callback=validate.scene_in_scenes,
+        ),
     ],
     group_name: Annotated[
         str, typer.Argument(..., show_default=False, help='Group name to hide')
     ],
 ):
     """Hide a group in a scene."""
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f'Scene [yellow]{scene_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_scene_item_list(scene_name)
     if (group := _get_group(group_name, resp)) is None:
         console.err.print(
@@ -154,17 +154,19 @@ def hide(
 def toggle(
     ctx: typer.Context,
     scene_name: Annotated[
-        str, typer.Argument(..., show_default=False, help='Scene name the group is in')
+        str,
+        typer.Argument(
+            ...,
+            show_default=False,
+            help='Scene name the group is in',
+            callback=validate.scene_in_scenes,
+        ),
     ],
     group_name: Annotated[
         str, typer.Argument(..., show_default=False, help='Group name to toggle')
     ],
 ):
     """Toggle a group in a scene."""
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f'Scene [yellow]{scene_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_scene_item_list(scene_name)
     if (group := _get_group(group_name, resp)) is None:
         console.err.print(
@@ -189,17 +191,19 @@ def toggle(
 def status(
     ctx: typer.Context,
     scene_name: Annotated[
-        str, typer.Argument(..., show_default=False, help='Scene name the group is in')
+        str,
+        typer.Argument(
+            ...,
+            show_default=False,
+            help='Scene name the group is in',
+            callback=validate.scene_in_scenes,
+        ),
     ],
     group_name: Annotated[
         str, typer.Argument(..., show_default=False, help='Group name to check status')
     ],
 ):
     """Get the status of a group in a scene."""
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f'Scene [yellow]{scene_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_scene_item_list(scene_name)
     if (group := _get_group(group_name, resp)) is None:
         console.err.print(

obsws_cli/media.py

@@ -0,0 +1,99 @@
+"""module containing commands for media inputs."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from . import console, util
+from .alias import SubTyperAliasGroup
+
+app = typer.Typer(cls=SubTyperAliasGroup)
+
+
+@app.callback()
+def main():
+    """Commands for media inputs."""
+
+
+@app.command('cursor | c')
+def cursor(
+    ctx: typer.Context,
+    input_name: Annotated[
+        str, typer.Argument(..., help='The name of the media input.')
+    ],
+    timecode: Annotated[
+        Optional[str],
+        typer.Argument(
+            ..., help='The timecode to set the cursor to (format: HH:MM:SS).'
+        ),
+    ] = None,
+):
+    """Get/set the cursor position of a media input."""
+    if timecode is None:
+        resp = ctx.obj['obsws'].get_media_input_status(input_name)
+        console.out.print(
+            f'Cursor for {console.highlight(ctx, input_name)} is at {util.milliseconds_to_timecode(resp.media_cursor)}.'
+        )
+        return
+
+    cursor_position = util.timecode_to_milliseconds(timecode)
+    ctx.obj['obsws'].set_media_input_cursor(input_name, cursor_position)
+    console.out.print(
+        f'Cursor for {console.highlight(ctx, input_name)} set to {timecode}.'
+    )
+
+
+@app.command('play | p')
+def play(
+    ctx: typer.Context,
+    input_name: Annotated[
+        str, typer.Argument(..., help='The name of the media input.')
+    ],
+):
+    """Get/set the playing status of a media input."""
+    ctx.obj['obsws'].trigger_media_input_action(
+        input_name, 'OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PLAY'
+    )
+    console.out.print(f'Playing media input {console.highlight(ctx, input_name)}.')
+
+
+@app.command('pause | pa')
+def pause(
+    ctx: typer.Context,
+    input_name: Annotated[
+        str, typer.Argument(..., help='The name of the media input.')
+    ],
+):
+    """Pause a media input."""
+    ctx.obj['obsws'].trigger_media_input_action(
+        input_name, 'OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PAUSE'
+    )
+    console.out.print(f'Paused media input {console.highlight(ctx, input_name)}.')
+
+
+@app.command('stop | s')
+def stop(
+    ctx: typer.Context,
+    input_name: Annotated[
+        str, typer.Argument(..., help='The name of the media input.')
+    ],
+):
+    """Stop a media input."""
+    ctx.obj['obsws'].trigger_media_input_action(
+        input_name, 'OBS_WEBSOCKET_MEDIA_INPUT_ACTION_STOP'
+    )
+    console.out.print(f'Stopped media input {console.highlight(ctx, input_name)}.')
+
+
+@app.command('restart | r')
+def restart(
+    ctx: typer.Context,
+    input_name: Annotated[
+        str, typer.Argument(..., help='The name of the media input.')
+    ],
+):
+    """Restart a media input."""
+    ctx.obj['obsws'].trigger_media_input_action(
+        input_name, 'OBS_WEBSOCKET_MEDIA_INPUT_ACTION_RESTART'
+    )
+    console.out.print(f'Restarted media input {console.highlight(ctx, input_name)}.')

obsws_cli/profile.py

@@ -62,15 +62,14 @@ def switch(
     profile_name: Annotated[
         str,
         typer.Argument(
-            ..., show_default=False, help='Name of the profile to switch to'
+            ...,
+            show_default=False,
+            help='Name of the profile to switch to',
+            callback=validate.profile_exists,
         ),
     ],
 ):
     """Switch to a profile."""
-    if not validate.profile_exists(ctx, profile_name):
-        console.err.print(f'Profile [yellow]{profile_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_profile_list()
     if resp.current_profile_name == profile_name:
         console.err.print(
@@ -87,14 +86,15 @@ def create(
     ctx: typer.Context,
     profile_name: Annotated[
         str,
-        typer.Argument(..., show_default=False, help='Name of the profile to create.'),
+        typer.Argument(
+            ...,
+            show_default=False,
+            help='Name of the profile to create.',
+            callback=validate.profile_not_exists,
+        ),
     ],
 ):
     """Create a new profile."""
-    if validate.profile_exists(ctx, profile_name):
-        console.err.print(f'Profile [yellow]{profile_name}[/yellow] already exists.')
-        raise typer.Exit(1)
-
     ctx.obj['obsws'].create_profile(profile_name)
     console.out.print(f'Created profile {console.highlight(ctx, profile_name)}.')
 
@@ -104,13 +104,14 @@ def remove(
     ctx: typer.Context,
     profile_name: Annotated[
         str,
-        typer.Argument(..., show_default=False, help='Name of the profile to remove.'),
+        typer.Argument(
+            ...,
+            show_default=False,
+            help='Name of the profile to remove.',
+            callback=validate.profile_exists,
+        ),
     ],
 ):
     """Remove a profile."""
-    if not validate.profile_exists(ctx, profile_name):
-        console.err.print(f'Profile [yellow]{profile_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     ctx.obj['obsws'].remove_profile(profile_name)
     console.out.print(f'Removed profile {console.highlight(ctx, profile_name)}.')

obsws_cli/scene.py

@@ -94,7 +94,12 @@ def current(
 def switch(
     ctx: typer.Context,
     scene_name: Annotated[
-        str, typer.Argument(..., help='Name of the scene to switch to')
+        str,
+        typer.Argument(
+            ...,
+            help='Name of the scene to switch to',
+            callback=validate.scene_in_scenes,
+        ),
     ],
     preview: Annotated[
         bool,
@@ -106,10 +111,6 @@ def switch(
         console.err.print('Studio mode is not enabled, cannot set the preview scene.')
         raise typer.Exit(1)
 
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f'Scene [yellow]{scene_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     if preview:
         ctx.obj['obsws'].set_current_preview_scene(scene_name)
         console.out.print(

obsws_cli/scenecollection.py

@@ -53,16 +53,15 @@ def current(ctx: typer.Context):
 def switch(
     ctx: typer.Context,
     scene_collection_name: Annotated[
-        str, typer.Argument(..., help='Name of the scene collection to switch to')
+        str,
+        typer.Argument(
+            ...,
+            help='Name of the scene collection to switch to',
+            callback=validate.scene_collection_in_scene_collections,
+        ),
     ],
 ):
     """Switch to a scene collection."""
-    if not validate.scene_collection_in_scene_collections(ctx, scene_collection_name):
-        console.err.print(
-            f'Scene collection [yellow]{scene_collection_name}[/yellow] not found.'
-        )
-        raise typer.Exit(1)
-
     current_scene_collection = (
         ctx.obj['obsws'].get_scene_collection_list().current_scene_collection_name
     )
@@ -82,16 +81,15 @@ def switch(
 def create(
     ctx: typer.Context,
     scene_collection_name: Annotated[
-        str, typer.Argument(..., help='Name of the scene collection to create')
+        str,
+        typer.Argument(
+            ...,
+            help='Name of the scene collection to create',
+            callback=validate.scene_collection_not_in_scene_collections,
+        ),
     ],
 ):
     """Create a new scene collection."""
-    if validate.scene_collection_in_scene_collections(ctx, scene_collection_name):
-        console.err.print(
-            f'Scene collection [yellow]{scene_collection_name}[/yellow] already exists.'
-        )
-        raise typer.Exit(1)
-
     ctx.obj['obsws'].create_scene_collection(scene_collection_name)
     console.out.print(
         f'Created scene collection {console.highlight(ctx, scene_collection_name)}.'

obsws_cli/sceneitem.py

@@ -24,6 +24,7 @@ def list_(
         typer.Argument(
             show_default='The current scene',
             help='Scene name to list items for',
+            callback=validate.scene_in_scenes,
         ),
     ] = None,
     uuid: Annotated[bool, typer.Option(help='Show UUIDs of scene items')] = False,
@@ -32,10 +33,6 @@ def list_(
     if not scene_name:
         scene_name = ctx.obj['obsws'].get_current_program_scene().scene_name
 
-    if not validate.scene_in_scenes(ctx, scene_name):
-        console.err.print(f'Scene [yellow]{scene_name}[/yellow] not found.')
-        raise typer.Exit(1)
-
     resp = ctx.obj['obsws'].get_scene_item_list(scene_name)
     items = sorted(
         (

obsws_cli/util.py

@@ -20,3 +20,28 @@ def check_mark(value: bool, empty_if_false: bool = False) -> str:
     if os.getenv('NO_COLOR', '') != '':
         return '✓' if value else '✗'
     return '✅' if value else '❌'
+
+
+def timecode_to_milliseconds(timecode: str) -> int:
+    """Convert a timecode string (HH:MM:SS) to total milliseconds."""
+    match timecode.split(':'):
+        case [mm, ss]:
+            hours = 0
+            minutes = int(mm)
+            seconds = int(ss)
+        case [hh, mm, ss]:
+            hours = int(hh)
+            minutes = int(mm)
+            seconds = int(ss)
+    return (hours * 3600 + minutes * 60 + seconds) * 1000
+
+
+def milliseconds_to_timecode(milliseconds: int) -> str:
+    """Convert total milliseconds to a timecode string (HH:MM:SS)."""
+    total_seconds = milliseconds // 1000
+    hours = total_seconds // 3600
+    minutes = (total_seconds % 3600) // 60
+    seconds = total_seconds % 60
+    if hours == 0:
+        return f'{minutes:02}:{seconds:02}'
+    return f'{hours:02}:{minutes:02}:{seconds:02}'

obsws_cli/validate.py

@@ -26,10 +26,13 @@ def input_not_in_inputs(ctx: typer.Context, input_name: str) -> bool:
     return input_name
 
 
-def scene_in_scenes(ctx: typer.Context, scene_name: str) -> bool:
+def scene_in_scenes(ctx: typer.Context, scene_name: str) -> str:
     """Check if a scene exists in the list of scenes."""
     resp = ctx.obj['obsws'].get_scene_list()
-    return any(scene.get('sceneName') == scene_name for scene in resp.scenes)
+    if not any(scene.get('sceneName') == scene_name for scene in resp.scenes):
+        console.err.print(f'Scene [yellow]{scene_name}[/yellow] not found.')
+        raise typer.Exit(1)
+    return scene_name
 
 
 def studio_mode_enabled(ctx: typer.Context) -> bool:
@@ -40,12 +43,32 @@ def studio_mode_enabled(ctx: typer.Context) -> bool:
 
 def scene_collection_in_scene_collections(
     ctx: typer.Context, scene_collection_name: str
-) -> bool:
+) -> str:
-    """Check if a scene collection exists."""
+    """Ensure a scene collection exists in the list of scene collections."""
     resp = ctx.obj['obsws'].get_scene_collection_list()
-    return any(
+    if not any(
         collection == scene_collection_name for collection in resp.scene_collections
+    ):
+        console.err.print(
+            f'Scene collection [yellow]{scene_collection_name}[/yellow] not found.'
         )
+        raise typer.Exit(1)
+    return scene_collection_name
+
+
+def scene_collection_not_in_scene_collections(
+    ctx: typer.Context, scene_collection_name: str
+) -> str:
+    """Ensure a scene collection does not already exist in the list of scene collections."""
+    resp = ctx.obj['obsws'].get_scene_collection_list()
+    if any(
+        collection == scene_collection_name for collection in resp.scene_collections
+    ):
+        console.err.print(
+            f'Scene collection [yellow]{scene_collection_name}[/yellow] already exists.'
+        )
+        raise typer.Exit(1)
+    return scene_collection_name
 
 
 def item_in_scene_item_list(
@@ -56,16 +79,22 @@ def item_in_scene_item_list(
     return any(item.get('sourceName') == item_name for item in resp.scene_items)
 
 
-def profile_exists(ctx: typer.Context, profile_name: str) -> bool:
+def profile_exists(ctx: typer.Context, profile_name: str) -> str:
-    """Check if a profile exists."""
+    """Ensure a profile exists."""
     resp = ctx.obj['obsws'].get_profile_list()
-    return any(profile == profile_name for profile in resp.profiles)
+    if not any(profile == profile_name for profile in resp.profiles):
+        console.err.print(f'Profile [yellow]{profile_name}[/yellow] not found.')
+        raise typer.Exit(1)
+    return profile_name
 
 
-def monitor_exists(ctx: typer.Context, monitor_index: int) -> bool:
+def profile_not_exists(ctx: typer.Context, profile_name: str) -> str:
-    """Check if a monitor exists."""
+    """Ensure a profile does not exist."""
-    resp = ctx.obj['obsws'].get_monitor_list()
+    resp = ctx.obj['obsws'].get_profile_list()
-    return any(monitor['monitorIndex'] == monitor_index for monitor in resp.monitors)
+    if any(profile == profile_name for profile in resp.profiles):
+        console.err.print(f'Profile [yellow]{profile_name}[/yellow] already exists.')
+        raise typer.Exit(1)
+    return profile_name
 
 
 def kind_in_input_kinds(ctx: typer.Context, input_kind: str) -> str: