Python library for communication with Tapo Cameras.

Used inside Home Assistant Integration HomeAssistant-Tapo-Control.

• Python3.13
• PIP modules installed

python3 -m pip install pytapo

from pytapo import Tapo

user = "" # user you set in Advanced Settings -> Camera Account
password = "" # password you set in Advanced Settings -> Camera Account
host = "" # ip of the camera, example: 192.168.1.52

tapo = Tapo(host, user, password)

print(tapo.getBasicInfo())

Depending on your camera model and firmware version, the authentication method varies.

Normally you should be able to authenticate using the "camera account" created via the Tapo App (Settings > Advanced settings > Camera account).

In case of a similar stack trace:

Traceback (most recent call last):
  File "/home/user/Projects/pytapo/pytapo/__init__.py", line 41, in __init__
    self.basicInfo = self.getBasicInfo()
  File "/home/user/Projects/pytapo/pytapo/__init__.py", line 232, in getBasicInfo
    return self.performRequest(
  File "/home/user/Projects/pytapo/pytapo/__init__.py", line 95, in performRequest
    self.ensureAuthenticated()
  File "/home/user/Projects/pytapo/pytapo/__init__.py", line 61, in ensureAuthenticated
    return self.refreshStok()
  File "/home/user/Projects/pytapo/pytapo/__init__.py", line 80, in refreshStok
    raise Exception("Invalid authentication data")
Exception: Invalid authentication data

Attempt to authenticate using admin as user and your TP-Link cloud account password as password.

Some newer firmware (for example Tapo C200 5.0 on 1.4.6) no longer accepts that login and answers with -40211. These cameras use a SPAKE2+ login instead, which pytapo detects and uses automatically. It needs your TP-Link cloud account password, passed either as password or as cloudPassword:

tapo = Tapo(host, "admin", password, cloudPassword=cloud_password)

Integration supports downloading recordings saved on camera's SD card.

See example script. You need to call it with following ENV values:

• HOST: IP Address of your camera
• PASSWORD_CLOUD: Tapo cloud account password, it is required to access the recordings, everything is still local
• OUTPUT: Directory where you wish to save all the recordings
• DATE: Date for which to download recordings in format of YYYYMMDD, for example 20230221.

You also need to have ffmpeg installed as that is used for converting the streams to watchable file.

Recordings are downloaded through the camera's encrypted streaming protocol (/stream). The camera does not expose the raw MP4 files directly, so a true "file copy" is not possible; the stream is AES-decrypted and the resulting MPEG-TS data is remuxed into an MP4 container by ffmpeg (the video track is copied as-is, the audio track is re-encoded to AAC).

Two stream requests exist for this. By default the Downloader sends the download request, the one the Tapo app sends when you tap download on a recording: the camera delivers the clip as fast as the link allows (about 10x realtime on Wi-Fi), with the full frame rate and the audio, and ends the stream itself at end_time. The older playback request plays the recording at realtime speed and keeps going past end_time, so a one minute clip takes a minute to download. If a camera does not accept the download request, the Downloader falls back to playback on its own.

The camera also keeps a thumbnail for every recording on the SD card (the picture the Tapo app shows in its playback list). You can fetch it without downloading the clip:

from pytapo.media_stream.snapshot import getRecordingSnapshot, getRecordingSnapshots

jpeg = await getRecordingSnapshot(tapo, recording["startTime"])      # bytes, or None
async for jpeg in getRecordingSnapshots(tapo, [r["startTime"] for r in recordings]):
    ...                                                               # one media session for all

You can tune the download behavior with the following Downloader parameters:

• output: mp4 (default, remuxed with ffmpeg) or ts to keep the MPEG-TS exactly as the camera sends it, no ffmpeg involved for the file itself. VLC and most players read it directly, audio included.
• method: download (default) or playback, see above.
• window_size: Affects throughput and stability. Higher values usually download faster but can cause some cameras to stop responding. Common values are 50 (stable) or 200 (default).
• progressInterval: Minimum time in seconds between progress updates (default 1.0). Increasing this value reduces CPU overhead because the library no longer runs an ffprobe subprocess on every chunk just to report progress. Use progressInterval=0 to restore the previous per-chunk behavior.
• stall_timeout: Seconds to wait for data before treating the stream as stalled and retrying (default 120).

Contributions to pytapo are welcomed.

By creating a PR you acknowledge and agree that you are not breaking any TOS, law and/or have a permission to provide and share the code changes.

Owner of this repository is not legally responsible for any PRs or code changes to this project created by 3rd parties.

When you make a new change to the code base, make sure to have 100% unit test coverage, see below for more information about tests.

Set the following environment variables:

PYTAPO_USER - user you set in Advanced Settings -> Camera Account

PYTAPO_PASSWORD - password you set in Advanced Settings -> Camera Account

PYTAPO_IP - ip of the camera, example: 192.168.1.52

Install pre-commit and tox from pip.

Run pre-commit install and pre-commit install -t pre-push.

Then run tox to run all the tests.

Linters are ran on every commit.

Tests are ran on push.

Your camera may do all the actions supported by this library, including, but not limited to, move, change privacy mode and reboot while tests are running. Camera does not format SD card during tests.

After the tests are done, your camera should be in the initial state.

• Dale Pavey from NCC Group for the initial research on the Tapo C200
• likaci and his github repository for the research on the Mercury camera on which tapo is based
• Tim Zhang for additional research for Mercury camera on his github repository
• Gábor Szabados for doing research and gathering all the information above in Home Assistant Community forum
• Davide Depau for additional research of the cameras and work on pytapo library
• Alex X for his incredible work on go2rtc library, and its code for Tapo stream communication which was rewritten to python in order to implement stream-related features of this library

See https://github.com/JurajNyiri/HomeAssistant-Tapo-Control?tab=readme-ov-file#troubleshooting--faq

Pytapo is an unofficial module for achieving interoperability with Tapo cameras.

Author is in no way affiliated with Tp-Link or Tapo.

All the api requests used within the library are available and published on the internet (examples linked above) and this module is purely just a wrapper around those https requests.

Author does not guarantee functionality of this library and is not responsible for any damage.

All product names, trademarks and registered trademarks in this repository, are property of their respective owners.