Hottub for Python

Host a small, live Audio Soak in the Hottub ecosystem.

pip install hottub
hottub audio-soak create --title "Python Porch" --now

Version 0.1 is intentionally focused: it discovers Hottubs you own or host, checks that Hottub voice and its production TURN relay are ready, creates a members-only Audio Soak, and can take it live. Participants join through the Hottub website or native apps.

The Python package does not access microphones, carry audio, record, transcribe, or contain the Harmonic Engine. Voice remains opt-in and is handled by Hottub's peer-to-peer WebRTC clients.

This repository contains only the public Python client. It does not contain or grant access to Hottub's private monorepo or proprietary Harmonic Engine implementation.

Requirements

• Python 3.10 or newer
• A Hottub account
• Owner or Host membership in at least one Hottub
• At most eight active voice participants during this beta

CLI

The CLI uses HOTTUB_TOKEN when present. Otherwise, it prompts for your email, password, and—when enabled—your authenticator or recovery code. Credentials and tokens are not written to disk.

# See the Tubs in which you may host.
hottub tubs --hostable

# Confirm that live audio and relay service are ready.
hottub audio-soak status

# Schedule for later. The timestamp must include its UTC offset.
hottub audio-soak create \
  --title "Evening Python Soak" \
  --start "2026-07-27T19:00:00-07:00"

# Open the room immediately.
hottub audio-soak create --title "Python Porch" --now

If you own or host more than one Hottub, pass the ID shown by hottub tubs --hostable:

hottub audio-soak create \
  --tub-id clx_example \
  --title "Maintainers' Soak" \
  --now

Python

from datetime import datetime, timezone
import os

from hottub import HottubClient

client = HottubClient(token=os.environ["HOTTUB_TOKEN"])
tub = client.list_tubs(hostable_only=True)[0]

soak = client.create_audio_soak(
    tub_id=tub.id,
    title="Python Porch",
    start_time=datetime.now(timezone.utc),
    go_live=True,
)
print(soak.url)

For interactive software, client.login(email, password) returns either a Session or TotpChallenge; complete the latter with client.verify_totp. Applications should keep bearer tokens in their platform's secure credential store and must never log them.

Beta boundaries

Audio Soaks created by this package are online, members-only, free, and use Hottub's existing hottub_audio room provider. The host is RSVP'd automatically. The beta does not expose room signaling, audio streams, recording, moderation automation, or proprietary Harmonic implementation details through Python.

License and security

This package is proprietary software distributed under the terms in LICENSE. Public source visibility does not make it open source. Please report vulnerabilities privately as described in SECURITY.md.