QUII Helper 📹

Python package for connecting to QUII / Qualvision-based cameras and video doorbells from code.

It can capture snapshots, save video clips, expose the camera as an RTSP stream, read available device metadata, and explicitly open a connected door without using the original mobile app.

What It Does ✨

• 📸 Captures JPEG snapshots from the camera preview stream.
• 🎞 Saves MP4/H.264 video clips for a user-selected duration.
• 📡 Serves the live preview as an RTSP stream for players such as VLC.
• 🔎 Reads cloud, LAN, storage, network, product, alarm, video, and capability information where the device supports it.
• 🧭 Discovers local devices that expose Qualvision-compatible HTTP services.
• Reads incoming-call cloud history with the experimental get_call_events() API, without push registration or door commands.
• Sends explicit local door-opening commands with Camera.open_door(); see Door Control for settings and acknowledgement semantics.

Compatibility 🔍

This project targets devices that use the QUII / Qualvision protocol family, including devices managed by the vHome 2.2 mobile app.

Useful discovery hints:

• A direct HTTP request to the device IP may return Server: Qualvision -HTTPServer.
• Many compatible devices expose TCP port 34567.
• Local read-only device methods usually require that your machine can reach the camera LAN IP.

Successfully tested devices:

• Tantos Marilyn Wi-Fi s: snapshot, MP4 capture, RTSP, door opening in auto mode, and incoming-call cloud history on the tested account/backend.

History access does not guarantee live delivery or a maximum notification delay. The library is also used by entrance-bot on Raspberry Pi ARM64; its mocked integration tests cover that deployment, not ARM64 media capture.

If another device works, please open an issue or pull request so the compatibility list can be expanded.

Quick Start 🚀

Use Python 3.10 or newer. For JPEG/MP4 output, also install the FFmpeg executable and put it on PATH (ffmpeg -version must work in the same environment). Installing this Python package does not install FFmpeg; see Media Prerequisites. RTSP and read-only device methods do not require FFmpeg.

For development or the bundled examples, install from a checkout:

git clone https://github.com/xaer981/quii-helper.git
cd quii-helper
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

For an application that only needs the library, install a built wheel instead:

python -m pip install /path/to/quii_helper-0.1.0rc6-py3-none-any.whl

0.1.0rc6 is a prepared candidate, not yet uploaded by this change. After a release is published on PyPI, python -m pip install --pre quii-helper selects an available pre-release. No repository checkout is needed for library use. The wheel does not include examples or .env.example; use the installed-package setup to create your own application directory and configuration.

Copy the required native assets extracted from the Android app into assets/:

assets/
  ca.pem
  client.pem
  client.txt
  libqv-p2p-v2.so

Use the verified vHome 2.2 arm64-v8a libqv-p2p-v2.so, regardless of your computer's architecture. Unsupported ELF/table layouts are rejected; files from other ABIs or app builds are not interchangeable without native verification.

Create .env from .env.example and fill in your account, device, cloud, and app constants:

CLOUD_ACCOUNT=
CLOUD_PASSWORD=
DEVICE_ID=
CLOUD_CLIENT_UUID=
CLOUD_AUTH_URL=
CLOUD_SERVICE_URL=
CAMERA_OEM=
CAMERA_APP_ID=
CAMERA_CLIENT_TYPE=
IP_REGION_ID=

Detailed extraction instructions are in docs/setup.md.

Basic Usage 🧩

from quii_helper import Camera, load_config

camera = Camera(config=load_config())

snapshot = camera.snapshot()
print(snapshot)

video = camera.save_video(duration_seconds=15)
print(video)

Start an RTSP stream:

from quii_helper import Camera, load_config

camera = Camera(config=load_config())

try:
    with camera.serve_rtsp(port=8554) as session:
        print(session.url)
        session.wait()
except KeyboardInterrupt:
    pass

Open the stream in VLC:

rtsp://127.0.0.1:8554/live

Alternatively, run python -m quii_helper.main to serve RTSP on port 8554 until Ctrl+C. This entry point does not open the door. RTSP binds to localhost by default. To serve a trusted LAN, explicitly pass host="0.0.0.0" and use the server's LAN IP in the player. There is no RTSP authentication or TLS: restrict access and do not expose the port publicly. Examples honor TLS_VERIFY (enabled by default). The editable main.py currently passes tls_verify=False for the owner's tested setup; remove that override to use configured TLS verification.

Read device information:

from quii_helper import Camera, load_config

camera = Camera(config=load_config())

print(camera.get_device_info())
print(camera.get_product_info())
print(camera.get_storage_info())
print(camera.get_network_info())

For the complete API reference, see docs/api.md.

load_config() explicitly reads .env from the working directory without changing the process environment. For embedding, pass an AutonomousConfig or use Camera(...) with process environment values and keyword arguments; neither reads .env implicitly. Assets and default outputs belong to the application (./assets and ./data), not the installed package. See Library Configuration.

Logging 🧾

The standalone entry point and examples configure console logging explicitly. Set LOG_LEVEL=info for user-friendly progress messages:

LOG_LEVEL=info

Set LOG_LEVEL=debug when collecting diagnostics for bug reports:

LOG_LEVEL=debug

Debug logging includes protocol counters, packet statistics, decoding summaries, and connection details.

Library logging is disabled by default and importing the package preserves application Loguru sinks. To use your own logging setup, call logger.enable("quii_helper") after importing the package. See Logging for the optional console helper.

Documentation 📚

• Setup And APK Extraction
• Camera API Reference
• Protocol Notes
• Compatibility Notes
• Contributing
• Security Policy

Important Notes ⚠️

• Do not commit .env, assets/, data/, logs, screenshots, or recordings.
• The package depends on native crypto/material extracted from the original Android app version you use.
• Some local read-only methods return error=-1 on devices that do not support that command.
• If cloud TLS fails with CERTIFICATE_VERIFY_FAILED, see Cloud Region And Auth URL.
• From a checkout, python -m examples.open_door is an explicit door-control check. It prints capability 24 and sends a real opening command using UNLOCK_PASSWORD and password_mode="auto"; do not use it as a read-only smoke test.

Status 🛠

The project is usable but still protocol-research-heavy. Public APIs are being stabilized around Camera, capture results, RTSP streaming, read-only device inspection, and explicit local door control.