dynamically load commands from obsws_cli.commands

no changes to files other than imports

patch bump

obsws_cli/__about__.py

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

obsws_cli/alias.py

@@ -24,6 +24,8 @@ class RootTyperAliasGroup(typer.core.TyperGroup):
                 cmd_name = 'hotkey'
             case 'i':
                 cmd_name = 'input'
+            case 'm':
+                cmd_name = 'media'
             case 'prf':
                 cmd_name = 'profile'
             case 'prj':
@@ -40,6 +42,8 @@ class RootTyperAliasGroup(typer.core.TyperGroup):
                 cmd_name = 'sceneitem'
             case 'ss':
                 cmd_name = 'screenshot'
+            case 'set':
+                cmd_name = 'settings'
             case 'st':
                 cmd_name = 'stream'
             case 'sm':

obsws_cli/app.py

@@ -2,6 +2,7 @@
 
 import importlib
 import logging
+import pkgutil
 from typing import Annotated
 
 import obsws_python as obsws
@@ -9,32 +10,15 @@ import typer
 
 from obsws_cli.__about__ import __version__ as version
 
-from . import config, console, styles
+from . import commands, config, console, styles
 from .alias import RootTyperAliasGroup
 
 app = typer.Typer(cls=RootTyperAliasGroup)
-for sub_typer in (
+for importer, modname, ispkg in pkgutil.iter_modules(
-    'filter',
+    commands.__path__, commands.__name__ + '.'
-    'group',
-    'hotkey',
-    'input',
-    'media',
-    'profile',
-    'projector',
-    'record',
-    'replaybuffer',
-    'settings',
-    'scene',
-    'scenecollection',
-    'sceneitem',
-    'screenshot',
-    'stream',
-    'studiomode',
-    'text',
-    'virtualcam',
 ):
-    module = importlib.import_module(f'.{sub_typer}', package=__package__)
+    subtyper = importlib.import_module(modname)
-    app.add_typer(module.app, name=sub_typer)
+    app.add_typer(subtyper.app, name=modname.split('.')[-1])
 
 
 def version_callback(value: bool):

obsws_cli/commands/filter.py

@@ -7,8 +7,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console, util
+from obsws_cli import console, util
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/group.py

@@ -6,9 +6,9 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console, util, validate
+from obsws_cli import console, util, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
-from .protocols import DataclassProtocol
+from obsws_cli.protocols import DataclassProtocol
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 
@@ -26,17 +26,14 @@ def list_(
         typer.Argument(
             show_default='The current scene',
             help='Scene name to list groups for',
+            callback=validate.scene_in_scenes,
         ),
     ] = None,
 ):
     """List groups in a scene."""
-    if not scene_name:
+    if scene_name is None:
         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/commands/hotkey.py

@@ -6,8 +6,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/input.py

@@ -7,8 +7,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console, util, validate
+from obsws_cli import console, util, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/media.py

@@ -4,8 +4,8 @@ from typing import Annotated, Optional
 
 import typer
 
-from . import console, util
+from obsws_cli import console, util, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 
@@ -24,7 +24,9 @@ def cursor(
     timecode: Annotated[
         Optional[str],
         typer.Argument(
-            ..., help='The timecode to set the cursor to (format: HH:MM:SS).'
+            ...,
+            help='The timecode to set the cursor to (format: HH:MM:SS).',
+            callback=validate.timecode_format,
         ),
     ] = None,
 ):

obsws_cli/commands/profile.py

@@ -6,8 +6,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console, util, validate
+from obsws_cli import console, util, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 
@@ -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/commands/projector.py

@@ -6,8 +6,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/record.py

@@ -5,8 +5,8 @@ from typing import Annotated, Optional
 
 import typer
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/replaybuffer.py

@@ -2,8 +2,8 @@
 
 import typer
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/scene.py

@@ -6,8 +6,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console, util, validate
+from obsws_cli import console, util, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 
@@ -70,14 +70,14 @@ def list_(
 def current(
     ctx: typer.Context,
     preview: Annotated[
-        bool, typer.Option(help='Get the preview scene instead of the program scene')
+        bool,
+        typer.Option(
+            help='Get the preview scene instead of the program scene',
+            callback=validate.studio_mode_enabled,
+        ),
     ] = False,
 ):
     """Get the current program scene or preview scene."""
-    if preview and not validate.studio_mode_enabled(ctx):
-        console.err.print('Studio mode is not enabled, cannot get preview scene.')
-        raise typer.Exit(1)
-
     if preview:
         resp = ctx.obj['obsws'].get_current_preview_scene()
         console.out.print(
@@ -94,22 +94,22 @@ 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,
-        typer.Option(help='Switch to the preview scene instead of the program scene'),
+        typer.Option(
+            help='Switch to the preview scene instead of the program scene',
+            callback=validate.studio_mode_enabled,
+        ),
     ] = False,
 ):
     """Switch to a scene."""
-    if preview and not validate.studio_mode_enabled(ctx):
-        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/commands/scenecollection.py

@@ -5,8 +5,8 @@ from typing import Annotated
 import typer
 from rich.table import Table
 
-from . import console, validate
+from obsws_cli import console, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 
@@ -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/commands/sceneitem.py

@@ -5,8 +5,8 @@ from typing import Annotated, Optional
 import typer
 from rich.table import Table
 
-from . import console, util, validate
+from obsws_cli import console, util, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 
@@ -24,18 +24,15 @@ 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,
 ):
     """List all items in a scene."""
-    if not scene_name:
+    if scene_name is None:
         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/commands/screenshot.py

@@ -6,8 +6,8 @@ from typing import Annotated
 import obsws_python as obsws
 import typer
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/settings.py

@@ -6,8 +6,8 @@ import typer
 from rich.table import Table
 from rich.text import Text
 
-from . import console, util
+from obsws_cli import console, util
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/stream.py

@@ -2,8 +2,8 @@
 
 import typer
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/studiomode.py

@@ -2,8 +2,8 @@
 
 import typer
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/text.py

@@ -4,8 +4,8 @@ from typing import Annotated, Optional
 
 import typer
 
-from . import console, validate
+from obsws_cli import console, validate
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/commands/virtualcam.py

@@ -2,8 +2,8 @@
 
 import typer
 
-from . import console
+from obsws_cli import console
-from .alias import SubTyperAliasGroup
+from obsws_cli.alias import SubTyperAliasGroup
 
 app = typer.Typer(cls=SubTyperAliasGroup)
 

obsws_cli/validate.py

@@ -1,5 +1,7 @@
 """module containing validation functions."""
 
+from typing import Optional
+
 import typer
 
 from . import console
@@ -8,7 +10,7 @@ from . import console
 skipped_option = typer.Option(parser=lambda _: _, hidden=True, expose_value=False)
 
 
-def input_in_inputs(ctx: typer.Context, input_name: str) -> bool:
+def input_in_inputs(ctx: typer.Context, input_name: str) -> str:
     """Ensure the given input exists in the list of inputs."""
     resp = ctx.obj['obsws'].get_input_list()
     if not any(input.get('inputName') == input_name for input in resp.inputs):
@@ -17,7 +19,7 @@ def input_in_inputs(ctx: typer.Context, input_name: str) -> bool:
     return input_name
 
 
-def input_not_in_inputs(ctx: typer.Context, input_name: str) -> bool:
+def input_not_in_inputs(ctx: typer.Context, input_name: str) -> str:
     """Ensure an input does not already exist in the list of inputs."""
     resp = ctx.obj['obsws'].get_input_list()
     if any(input.get('inputName') == input_name for input in resp.inputs):
@@ -26,26 +28,57 @@ 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: Optional[str]) -> str | None:
     """Check if a scene exists in the list of scenes."""
+    if scene_name is None:
+        return
+
     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:
+def studio_mode_enabled(ctx: typer.Context, preview: bool) -> bool:
-    """Check if studio mode is enabled."""
+    """Ensure studio mode is enabled if preview option is used."""
     resp = ctx.obj['obsws'].get_studio_mode_enabled()
-    return resp.studio_mode_enabled
+    if preview and not resp.studio_mode_enabled:
+        console.err.print(
+            'Studio mode is disabled. This action requires it to be enabled.'
+        )
+        raise typer.Exit(1)
+    return preview
 
 
 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 +89,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:
@@ -75,3 +114,29 @@ def kind_in_input_kinds(ctx: typer.Context, input_kind: str) -> str:
         console.err.print(f'Input kind [yellow]{input_kind}[/yellow] not found.')
         raise typer.Exit(1)
     return input_kind
+
+
+def timecode_format(ctx: typer.Context, timecode: Optional[str]) -> str | None:
+    """Validate that a timecode is in HH:MM:SS or MM:SS format."""
+    if timecode is None:
+        return
+
+    match timecode.split(':'):
+        case [mm, ss]:
+            if not (mm.isdigit() and ss.isdigit()):
+                console.err.print(
+                    f'Timecode [yellow]{timecode}[/yellow] is not valid. Use MM:SS or HH:MM:SS format.'
+                )
+                raise typer.Exit(1)
+        case [hh, mm, ss]:
+            if not (hh.isdigit() and mm.isdigit() and ss.isdigit()):
+                console.err.print(
+                    f'Timecode [yellow]{timecode}[/yellow] is not valid. Use MM:SS or HH:MM:SS format.'
+                )
+                raise typer.Exit(1)
+        case _:
+            console.err.print(
+                f'Timecode [yellow]{timecode}[/yellow] is not valid. Use MM:SS or HH:MM:SS format.'
+            )
+            raise typer.Exit(1)
+    return timecode