Metadata-Version: 2.4
Name: tp-link-vigi-sdk
Version: 0.3.0
Summary: Python SDK for TP-Link VIGI NVR OpenAPI.
Author-email: 김건우 <gunwookim0221@gmail.com>
License: MIT License
        
        Copyright (c) 2026 김건우
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/gunwookim0221/tp-link-vigi-sdk
Project-URL: Repository, https://github.com/gunwookim0221/tp-link-vigi-sdk
Project-URL: Issues, https://github.com/gunwookim0221/tp-link-vigi-sdk/issues
Project-URL: Documentation, https://github.com/gunwookim0221/tp-link-vigi-sdk/blob/main/docs/00-index.md
Keywords: tp-link,vigi,nvr,openapi,python,sdk,rtsp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: coverage>=7; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# TP-Link VIGI SDK

Python SDK for the documented, read-only portions of the
TP-Link VIGI NVR OpenAPI.

## Requirements and Installation

- Python 3.10 or later.

Install the project in an isolated environment from the repository root:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
```

## Quickstart

Set the NVR connection variables in your shell. `.env` is not loaded
automatically by the SDK, tests, or examples.

```powershell
$env:VIGI_HOST = "nvr.example.invalid"
$env:VIGI_PORT = "20443"
$env:VIGI_USERNAME = "admin"
$env:VIGI_PASSWORD = "<your-nvr-password>"
$env:VIGI_VERIFY_SSL = "true"
```

Then authenticate and list NVR-managed devices:

```python
import os

from vigi import AuthConfig, VigiClient

client = VigiClient(
    AuthConfig(
        host=os.environ["VIGI_HOST"],
        port=int(os.getenv("VIGI_PORT", "20443")),
        username=os.environ["VIGI_USERNAME"],
        password=os.environ["VIGI_PASSWORD"],
        verify_tls=os.getenv("VIGI_VERIFY_SSL", "true").lower() not in {"0", "false", "no"},
    )
)
client.login()
devices = client.devices.list_added_devices()
for device in devices.devices:
    print(device.channel_id, device.name, device.alias, device.online.value)
```

`client.login()` and service calls contact the configured NVR. Constructing a
client or importing `vigi` does not make a network request.

## Read-only workflows and examples

The detailed [usage guide](docs/12-usage-guide.md) covers authentication,
module discovery, device inventory, recording-day and recording-result
searches, current snapshots, explicit error handling, and RTSP live/replay URL
construction.

- [List devices](examples/list_devices.py)
- [Read-only recording workflow](examples/read_only_workflow.py)
- [Build a replay URL without logging in](examples/build_replay_url.py)

Examples read environment variables only when their `main()` function runs.
They do not load `.env`, print passwords or tokens, save files, or open RTSP
connections.

## Supported scope

Implemented read-only SDK support includes:

- Documented NVR authentication.
- Documented NVR module/version discovery with `client.capabilities.list_modules()`.
- NVR-managed device inventory with `client.devices.list_added_devices()`.
- Recording-day, free-search-process, and recording-result queries.
- `client.stream.build_live_url(...)` for documented RTSP live URLs.
- `client.stream.build_ipc_live_url(...)` for documented standalone-camera RTSP live URLs.
- Current NVR snapshots as in-memory JPEG bytes with
  `client.snapshots.get_snapshot(channel_id)`.
- `client.stream.build_replay_url(...)` for documented RTSP replay URLs.
- V1.4 management APIs for recording control, device scan, device add/remove,
  and RTSP-device registration.
- V1.4 PTZ capability/control, preset/tour listing, target tracking, audio, and
  alarm-output service groups through `client.ptz`, `client.audio`, and
  `client.alarm_outputs`.

The RTSP helpers only build URLs. They do not open RTSP, perform a Digest
handshake, download video, or save video files. Live URLs support main stream
`1` and minor stream `2`; replay requires stream `1` and explicit UTC
`YYYYMMDDtHHMMSSz` times. HTTPS OpenAPI Bearer authentication is separate from
RTSP Digest authentication and is not included in generated URLs.

Module discovery and snapshots are unit/contract tested and were verified in
the real-NVR read-only pass recorded in the [V1.4 compatibility report](docs/openapi/nvr-openapi-v1.4-compatibility-2026-09-20.md).
Snapshot support returns the current channel image only; it does not save files
or capture historical frames.

The following V1.4 management APIs are also implemented with mock/contract
coverage, but have not been run against a real NVR:

- `client.records.set_record_control(channel_id, RecordControlMode)`.
- `client.devices.scan_devices()`.
- `client.devices.add_device(...)` and `client.devices.remove_device(...)`.
- `client.devices.add_rtsp_device(...)`.

These calls are explicit state-changing operations where applicable. They do
not retry automatically, infer local device state, or select scan results.

Phase 3B hardware-control APIs are implemented with mock/contract coverage.
Read-only capability and state checks were exercised against a real NVR as
recorded in the [V1.4 compatibility report](docs/openapi/nvr-openapi-v1.4-compatibility-2026-09-20.md),
but hardware mutations were not. They are exposed through
`client.ptz`, `client.audio`, and `client.alarm_outputs` for the documented
PTZ capability/movement/park/preset-tour reads/target-tracking, audio
capability and sound controls, and alarm-output capability/configuration/manual
control endpoints. The tested NVR's PTZ batch capability response was a
documented device/documentation deviation with omitted fields; the SDK keeps
strict validation. PTZ direction remains an explicit numeric field because the
official document does not define a numeric direction mapping. The document
does not define preset/tour mutation endpoints, so none are exposed.

Unsupported or deferred:

- Direct standalone IPC/camera snapshot APIs; IPC OpenAPI V1.1 still has no
  documented snapshot method.
- Export/download, RTSP playback, video saving, ffmpeg, and image processing.
- CLI: deferred to a separate phase.
- Standalone IPC OpenAPI control APIs.
- Hardware mutation verification against a real NVR or camera.

## Tests

Run the default unit and smoke-test suite:

```powershell
python -m pytest
```

Real-device integration tests are opt-in. Export the required `VIGI_*`
variables in the shell, then run the relevant test explicitly, for example:

```powershell
python -m pytest tests/test_integration_records.py -v
```

See [docs/05-test-strategy.md](docs/05-test-strategy.md) and
[.env.example](.env.example) for the supported local configuration variables.

## Documentation

Start with:

- [Documentation index](docs/00-index.md)
- [API scope](docs/03-api-scope.md)
- [Usage guide](docs/12-usage-guide.md)
- [Implementation checklist](docs/08-implementation-checklist.md)
- [Limitations](docs/10-limitations.md)
- [Roadmap](docs/11-roadmap.md)

## License

This project is licensed under the [MIT License](LICENSE).

## Disclaimer

This project is not affiliated with, endorsed by, or sponsored by TP-Link.
TP-Link and VIGI are trademarks of their respective owners. Use this SDK only
with devices and credentials you are authorized to access.
