Metadata-Version: 2.4
Name: hottub
Version: 0.1.0
Summary: Host Audio Soaks in the Hottub ecosystem.
Author: Hottub
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://joinhottub.com
Project-URL: Repository, https://github.com/joinhottub/hottub-python
Project-URL: Security, https://github.com/joinhottub/hottub-python/security/policy
Keywords: hottub,audio,community,voice
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Hottub for Python

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

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

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

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

## Python

```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`](LICENSE). Public source visibility does not make it open source.
Please report vulnerabilities privately as described in
[`SECURITY.md`](SECURITY.md).
