Splash

splash

Push a full-screen splash image to a connected Stream Deck.

Uploads a single image covering the entire back-panel LCD via HID command 0x08 (Update Full Screen Image). Intended as a quick way to test the splash pipeline against real hardware without writing any Python.

Examples:

::

# Push an image, fitting with cover (default), to the first deck:
python -m deux.tools.splash --image boot.png

# Letterbox with a coloured background:
python -m deux.tools.splash --image logo.svg --fit contain --background "#1a1a2e"

# Clear the screen to solid black:
python -m deux.tools.splash --clear

Notes

The full-screen image is a one-shot whole-LCD blit. Any subsequent key or window update (including by another running deux process) will paint over it. See :class:deux.runtime.deck.Deck.show_full_screen_image for details.

main

main(argv: list[str] | None = None) -> int

Entry point for python -m deux.tools.splash.

Parameters:

Name	Type	Description	Default
argv	list[str] or None	Argument vector (excluding the program name). Defaults to :data:sys.argv when None.	None

Returns:

Type	Description
int	Process exit code. 0 on success, 1 on bad arguments or no device, 2 on image preparation / HID error.

Source code in src/deux/tools/splash.py

def main(argv: list[str] | None = None) -> int:
    """Entry point for ``python -m deux.tools.splash``.

    Parameters
    ----------
    argv : list[str] or None, optional
        Argument vector (excluding the program name).  Defaults to
        :data:`sys.argv` when ``None``.

    Returns
    -------
    int
        Process exit code.  ``0`` on success, ``1`` on bad arguments
        or no device, ``2`` on image preparation / HID error.
    """
    parser = _build_parser()
    args = parser.parse_args(argv)

    if args.image is None and not args.clear:
        parser.error("Either --image or --clear is required")
    if args.image is not None and args.clear:
        parser.error("--image and --clear are mutually exclusive")

    logging.basicConfig(
        level=logging.DEBUG if args.verbose else logging.INFO,
        format="%(levelname)s %(name)s: %(message)s",
    )

    # Lazy imports: avoid pulling resvg / Pillow / HID into module load.
    from deux.runtime.splash import (  # noqa: PLC0415
        SplashError,
        prepare_full_screen_jpeg,
        prepare_solid_color_jpeg,
    )

    device = _find_first_device()
    logical_size = device.logical_lcd_size
    if logical_size == (0, 0):
        print(  # noqa: T201
            f"ERROR: Device PID 0x{device.product_id:04X} ({device.family}) "
            "has no known LCD size for the full-screen image path.",
            file=sys.stderr,
        )
        device.close()
        return 2

    try:
        if args.clear:
            print(  # noqa: T201
                f"Clearing {device.family} ({logical_size[0]}x{logical_size[1]}) "
                f"to RGB{args.background}",
                file=sys.stderr,
            )
            jpeg = prepare_solid_color_jpeg(
                args.background,
                logical_size=logical_size,
                rotation=device.rotation,
                jpeg_quality=args.quality,
            )
        else:
            print(  # noqa: T201
                f"Pushing {args.image} to {device.family} "
                f"({logical_size[0]}x{logical_size[1]}, fit={args.fit})",
                file=sys.stderr,
            )
            jpeg = prepare_full_screen_jpeg(
                args.image,
                logical_size=logical_size,
                rotation=device.rotation,
                fit=args.fit,
                background=args.background,
                jpeg_quality=args.quality,
            )

        device.set_full_screen_image(jpeg)
    except SplashError as exc:
        print(f"ERROR: {exc}", file=sys.stderr)  # noqa: T201
        device.close()
        return 2
    except Exception as exc:  # noqa: BLE001 — final user-facing barrier
        print(f"ERROR: {exc}", file=sys.stderr)  # noqa: T201
        device.close()
        return 2

    device.close()
    print("Done.", file=sys.stderr)  # noqa: T201
    return 0