Metadata-Version: 2.4
Name: smartcam-local
Version: 0.1.0
Summary: Local Python client and CLI for Samsung SmartCam stw-cgi-rest cameras
Author: Samsung SmartCam Local contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/aeonik/samsung-smartcam-local
Project-URL: Issues, https://github.com/aeonik/samsung-smartcam-local/issues
Keywords: samsung,smartcam,ptz,camera,home-assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# 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:

```bash
python3 -m pip install smartcam-local
```

From a checkout:

```bash
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:

   ```bash
   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:

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

Use an environment variable:

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

Use a local password manager command without invoking a shell:

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

PTZ examples:

```bash
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:

```bash
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

```python
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:

```text
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:

```json
{"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:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

Run the CLI from source:

```bash
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.
