Metadata-Version: 2.4
Name: macstt
Version: 0.1.1
Summary: Native macOS speech-to-text for Python using Apple's Speech framework
Author: Sakhi Saswat Panda
License: MIT
Project-URL: Repository, https://github.com/PandaTGOS/macstt
Project-URL: Issues, https://github.com/PandaTGOS/macstt/issues
Keywords: speech,speech-recognition,speech-to-text,stt,macos,apple,swift,dictation,voice,transcription
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# macstt

> Native macOS speech-to-text for Python using Apple's Speech framework.

`macstt` is a lightweight Python library that provides real-time speech recognition on macOS by wrapping Apple's native Speech framework through a dedicated Swift helper process.

Unlike cloud-based speech APIs, `macstt` performs speech recognition using the operating system's built-in capabilities and exposes a clean, Pythonic interface for streaming transcription.

---

## Features

- Native macOS Speech Recognition
- Real-time streaming transcription
- Partial and final recognition results
- On-device processing supported by Apple's Speech framework
- Typed Python event models
- Context manager API
- Iterator-based event streaming
- Bundled native helper executable
- No third-party speech engines
- Simple JSON protocol between Python and Swift

---

## Requirements

- macOS 11 (Big Sur) or later
- Apple Silicon (ARM64)
- Python 3.10+

`macstt` currently supports Apple Silicon Macs only.

---

## Installation

```bash
pip install macstt
```

No additional native dependencies are required.

---

## Quick Start

```python
from macstt import STT

with STT() as stt:

    stt.start()

    for event in stt:
        print(event)
```

Example output:

```text
StatusEvent(type='started', timestamp=...)

SpeechEvent(
    type='speech',
    text='Hello world',
    is_final=False,
    timestamp=...
)

SpeechEvent(
    type='speech',
    text='Hello world',
    is_final=True,
    timestamp=...
)
```

---

## API Overview

The primary interface is the `STT` class.

```python
from macstt import STT

stt = STT()
```

The object manages the lifecycle of the native speech recognition helper.

Typical usage is through a context manager:

```python
with STT() as stt:
    ...
```

---

## Starting Recognition

```python
stt.start()
```

Begins streaming speech recognition.

---

## Stopping Recognition

```python
stt.stop()
```

Stops the active recognition session.

---

## Receiving Events

`STT` is iterable.

Each iteration yields a typed event object.

```python
for event in stt:
    print(event)
```

---

## Event Types

### StatusEvent

Lifecycle events generated by the recognizer.

```python
StatusEvent(
    type="started",
    timestamp=...
)
```

or

```python
StatusEvent(
    type="stopped",
    timestamp=...
)
```

---

### SpeechEvent

Represents recognized speech.

```python
SpeechEvent(
    type="speech",
    text="Hello world",
    is_final=False,
    timestamp=...
)
```

Fields:

| Field | Description |
|--------|-------------|
| `text` | Recognized transcript |
| `is_final` | Whether recognition is complete |
| `timestamp` | Event timestamp |

---

## How It Works

`macstt` intentionally separates Python from the platform-specific implementation.

```
Python
    │
    ▼
macstt
    │
    ▼
JSON protocol
    │
    ▼
Swift helper
    │
    ▼
Apple Speech Framework
```

The Python package never directly calls Apple's Speech APIs.

Instead, a small Swift executable owns all native functionality and communicates with Python using newline-delimited JSON messages over standard input and output.

This design keeps the Python interface lightweight while isolating all platform-specific implementation details.

---

## Design Goals

The project is designed around a few core principles:

- Small, focused Python API
- Native macOS implementation
- Minimal dependencies
- Streaming-first interface
- Clear separation between Python and native code
- Language-agnostic communication protocol

---

## Limitations

Current limitations include:

- macOS only
- Apple Silicon (ARM64) only
- Requires microphone access permission
- Uses Apple's Speech framework and its platform capabilities

---

## Documentation

Project repository:

https://github.com/PandaTGOS/macstt

Issue tracker:

https://github.com/PandaTGOS/macstt/issues

---

## License

MIT License.
