Metadata-Version: 2.5
Name: kymoscope
Version: 0.3.0
Summary: Stream live, end-to-end encrypted telemetry to Kymoscope
Project-URL: Homepage, https://kymoscope.com
Project-URL: Documentation, https://kymoscope.com/docs/live
License: # Kymoscope SDK License Agreement
        
        Copyright © 2026 Kymoscope. All rights reserved.
        
        This is proprietary software. It is licensed, not sold. By installing, copying
        or using the Kymoscope SDK (the "Software") you agree to these terms. If you do not
        agree, do not use the Software.
        
        > Template notice for the owner: this agreement was drafted as a starting point.
        > Have it reviewed by a lawyer for your jurisdiction and fill in the legal
        > entity, governing law and contact details before relying on it.
        
        ## 1. Licenses
        
        **1.1 Evaluation.** You may use the Software without a license key to evaluate
        it and to develop your integration. Unlicensed use displays a "Powered by
        Kymoscope" attribution in the workspace.
        
        **1.2 Production.** Using the Software in a product, service or internal tool
        made available to anyone other than your own developers ("Production Use")
        requires a valid license key issued by Kymoscope for each domain the Software is
        served from, under an order or agreement with Kymoscope.
        
        **1.3 Scope.** A license key is personal to the licensee named in it, for the
        domains listed in it and until its expiry date.
        
        ## 2. Restrictions
        
        You must not, and must not allow others to:
        
        1. make the Software available in Production Use without a valid license key
           for that domain;
        2. remove, hide, obscure or alter the attribution shown by unlicensed use, or
           the copyright notices in the Software;
        3. circumvent, disable or modify the license check, or create, alter or share
           license keys;
        4. copy, sell, sublicense, distribute or publish the Software, or offer it as a
           standalone component library or SDK, except as embedded in your own product
           as permitted above;
        5. reverse engineer, decompile or disassemble the Software, except to the
           extent applicable law expressly permits it despite this restriction;
        6. use the Software to build a competing embeddable analytics or charting
           product.
        
        ## 3. Kymoscope services
        
        Live-stream relaying, watch tickets and other hosted services are provided
        under your Kymoscope account terms and may be rate limited or suspended for abuse.
        
        ## 4. Ownership
        
        Kymoscope and its licensors own all rights in the Software. No rights are granted
        except those expressly stated here.
        
        ## 5. Termination
        
        This license ends automatically if you breach it. On termination you must stop
        using the Software and delete all copies.
        
        ## 6. No warranty and limitation of liability
        
        The Software is provided "as is", without warranties of any kind. To the
        maximum extent permitted by law, Kymoscope is not liable for any indirect,
        incidental or consequential damages, and its total liability is limited to the
        fees you paid for the Software in the twelve months before the claim.
        
        ## 7. Contact
        
        For license keys and commercial terms, contact Kymoscope.
License-File: LICENSE.md
Requires-Python: >=3.9
Requires-Dist: cryptography>=41
Requires-Dist: requests>=2.28
Requires-Dist: websocket-client>=1.6
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: viewer
Requires-Dist: msgpack>=1.0; extra == 'viewer'
Description-Content-Type: text/markdown

# kymoscope

Stream live, end-to-end encrypted telemetry to [Kymoscope](https://kymoscope.com) from Python.

Requires Python 3.9 or later.

```bash
pip install kymoscope
```

## Example

```python
import math, time
from kymoscope import LiveStream

API_KEY = "kymoscope_..."   # Account -> API & real-time streaming, or a project's API key
# state_path keeps this sender's identity, so a restart needs no new approval
with LiveStream(API_KEY, "Rig A", state_path="kymoscope-state.json") as stream:
    print("stream id:", stream.stream_id)
    while True:
        t = time.time()           # absolute (Unix seconds)
        stream.send([{"t": t, "signals": [
            {"name": "speed", "unit": "m/s", "value": 50 + 10 * math.sin(t)},
        ]}])
        time.sleep(1 / 60)
```

In an end-to-end encrypted project, the first run waits until a project member's browser
approves the sender; after that it publishes on its own.

## Keep every sample when the connection drops

```python
with LiveStream(API_KEY, "Rig A", state_path="kymoscope-state.json",
                buffer_path="kymoscope-buffer", buffer_max_mb=2048) as stream:
    ...
```

With `buffer_path` (a folder), the stream always sends, also with nobody watching, so a cloud
recording keeps everything. While the relay is unreachable it keeps the encrypted messages on disk, then sends
them in order when the relay is back, with the bandwidth live data leaves spare. Viewers see that data in the
recording, not in the live view. A crash can send a few messages twice.
`buffer_max_mb` caps the disk used; when it is full, new samples are dropped and counted in `stream.buffer_dropped`.
Since 0.3.0 the stream sends the compact format by default (4–8× less data); `block_format=False` sends the
classic format for viewers on SDK versions before 0.2.0 or self-hosted relays before 0.2.0 (`buffer_path` always
uses the compact one). With `buffer_path`, send absolute times (`time.time()`), so data sent after a restart lands
in the right place in the recording.

The headless viewer (`kymoscope.viewer`) needs msgpack: `pip install 'kymoscope[viewer]'`.

Full documentation: https://kymoscope.com/docs/live
