smartcam-local 0.1.0

Local Python client and CLI for Samsung SmartCam stw-cgi-rest cameras

Samsung SmartCam Local

Local Python client and CLI for Samsung SmartCam cameras that expose the stw-cgi-rest API.

This project is for people keeping older SmartCam hardware useful after cloud app support changed or disappeared. It talks directly to the camera on your LAN with HTTP Digest authentication. It does not use Samsung cloud services and does not include proprietary vendor materials, firmware, or private infrastructure details.

Status

Early but usable. PTZ has been tested against:

• SNH-V6410PN
• firmware 1.18_180413

Other Samsung SmartCam models may work if they expose the same local /stw-cgi-rest/... endpoints. Please open issues with model, firmware, and which commands work or fail.

Features

• Zero runtime dependencies.
• HTTP Digest auth implemented with the Python standard library.
• CLI for one-off control and scripting.
• Python API for Home Assistant custom integrations, HACS projects, Scrypted helpers, or local automation.
• PTZ continuous move, timed nudge, stop, relative move, and preset recall.
• Read-only device, network, image, and flip status calls.

Install

From PyPI:

python3 -m pip install smartcam-local

From a checkout:

python3 -m pip install -e .

Release

Releases publish to PyPI through GitHub Actions and PyPI Trusted Publishing.

1. Update version in pyproject.toml.

2. Commit the version change.

3. Push a matching tag:

   git tag v0.1.0
   git push origin v0.1.0
   

The publish workflow builds the source distribution and wheel, checks package metadata, then publishes to PyPI from the protected pypi environment.

CLI Quick Start

The camera username is usually admin.

Prompt for the password:

smartcam-local --host 192.168.1.50 ptz down --duration 0.5

Use an environment variable:

export SMARTCAM_PASSWORD='your camera password'
smartcam-local --host 192.168.1.50 info

Use a local password manager command without invoking a shell:

smartcam-local --host 192.168.1.50 --password-command 'pass show home/camera' ptz stop

PTZ examples:

smartcam-local --host 192.168.1.50 ptz up --duration 0.4
smartcam-local --host 192.168.1.50 ptz left --duration 0.8
smartcam-local --host 192.168.1.50 ptz stop
smartcam-local --host 192.168.1.50 move --pan 0 --tilt -1 --duration 0.6
smartcam-local --host 192.168.1.50 relative down
smartcam-local --host 192.168.1.50 preset 1

Read-only examples:

smartcam-local --host 192.168.1.50 info
smartcam-local --host 192.168.1.50 network
smartcam-local --host 192.168.1.50 image
smartcam-local --host 192.168.1.50 flip

Python API

from smartcam_local import SmartCamClient

camera = SmartCamClient(
    host="192.168.1.50",
    username="admin",
    password="camera-password",
)

print(camera.device_info())

# Timed continuous movement: move, sleep, stop.
camera.nudge("down", duration=0.5)

# Low-level PTZ calls are available too.
camera.continuous_move(pan=0, tilt=-1)
camera.stop()
camera.relative_move(pan=0, tilt=1)
camera.goto_preset(1)

Supported Local Endpoints

The following routes are implemented:

GET /stw-cgi-rest/system/deviceinfo
GET /stw-cgi-rest/network/interface
GET /stw-cgi-rest/image/camera
GET /stw-cgi-rest/image/flip

PUT /stw-cgi-rest/ptzcontrol/continuous
PUT /stw-cgi-rest/ptzcontrol/relative
PUT /stw-cgi-rest/ptzcontrol/preset

Continuous PTZ payloads use:

{"Channel":0,"Pan":0,"Tilt":-1}

Observed movement values:

Direction	Pan	Tilt
stop	0	0
left	-1	0
right	1	0
up	0	1
down	0	-1

Continuous movement behaves like press-and-hold: send a direction, wait briefly, then send stop. The CLI and SmartCamClient.nudge() do this for you.

Password Safety

Avoid putting camera passwords in RTSP URLs, shell history, scripts, or issue reports. Prefer one of:

• interactive prompt
• SMARTCAM_PASSWORD
• --password-file
• --password-command, such as a password manager command

The CLI runs --password-command with shlex.split() and subprocess, not through a shell.

Home Assistant Integration Notes

This package is intentionally small so a Home Assistant integration can depend on it or vendor it. A useful first integration surface would be:

• camera entity using the existing RTSP stream URL configured by the user
• PTZ actions for up, down, left, right, and stop
• preset recall actions
• sensors for model, firmware, network, day/night, and flip state

The API is synchronous today. A future Home Assistant integration may want an async wrapper or native async client.

Clean-Room Boundary

This repository contains original code and compatibility notes derived from observed device behavior. Do not commit proprietary vendor materials, camera credentials, private network hostnames, private IPs, jump boxes, or infrastructure details.

Development

Run tests:

PYTHONPATH=src python3 -m unittest discover -s tests

Run the CLI from source:

PYTHONPATH=src python3 -m smartcam_local --host 192.168.1.50 info

License

Original code in this repository is licensed under the Apache License 2.0.

This project is independent and is not affiliated with Samsung, Hanwha Vision, or Wisenet. Product names and trademarks belong to their respective owners.