https://github.com/arach/ora
Last synced: 14 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/arach/ora
- Owner: arach
- License: mit
- Created: 2026-03-17T20:52:09.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-23T19:23:20.000Z (3 months ago)
- Last Synced: 2026-03-24T13:31:24.374Z (3 months ago)
- Language: TypeScript
- Size: 1.49 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Ora
`Ora` is a TypeScript-first text-to-speech runtime for provider integration, voice discovery, and synthesis execution.
Repository: [github.com/arach/ora](https://github.com/arach/ora)
The package is intentionally small:
- provider registration and request normalization
- credential injection and runtime lifecycle instrumentation
- stable voice discovery
- buffered and streaming synthesis
- optional playback utilities for apps that need stateful tracking
## Why this exists
TTS providers and model hosts differ in API shape, authentication, and voice catalogs.
`Ora` gives you one integration surface so your app can:
- discover voices per provider
- synthesize speech through a stable request/response contract
- keep provider details and credentials out of host app business logic
## Install
```bash
bun add @arach/ora
```
`@arach/ora` also installs cleanly with `pnpm add @arach/ora` and
`npm install @arach/ora`.
The published package ships with:
- ESM and CommonJS entrypoints
- bundled TypeScript declarations for both module systems
- the `ora-worker` CLI for local or remote worker processes
## Basic setup
```ts
import {
OraBufferedInstrumentationSink,
OraMemoryCacheStore,
OraMemoryCredentialStore,
createOraRuntime,
createOpenAiTtsProvider,
} from "@arach/ora";
const runtime = createOraRuntime({
providers: [createOpenAiTtsProvider()],
cacheStore: new OraMemoryCacheStore(),
credentialStore: new OraMemoryCredentialStore(),
instrumentation: [new OraBufferedInstrumentationSink()],
});
const openai = runtime.provider("openai");
openai.setCredentials({
apiKey: process.env.OPENAI_API_KEY ?? "",
});
const voices = await openai.listVoices();
const response = await openai.synthesize({
text: "Hello from Ora.",
voice: voices[0]?.id ?? "alloy",
format: "mp3",
});
const providers = await runtime.listProviderSummaries();
const catalog = await runtime.catalog();
const cachedEntries = await runtime.queryCache({ provider: "openai" });
```
`response` is normalized into a consistent schema regardless of backend:
`response.audio` carries the real asset reference for playback: inline bytes, a URL, or both.
## Streaming
```ts
for await (const event of openai.stream({
text: "Streaming is optional.",
format: "wav",
preferences: {
priority: "responsiveness",
},
})) {
console.log(event.type, event.timeMs);
}
```
The `stream` API is shared across providers that support it.
## Remote worker
If you want to keep inference on another machine (for example a Mac mini), run a worker and connect it through `createRemoteTtsProvider(...)`.
After installing the package, run the worker with your package manager's exec command:
```bash
bunx ora-worker init --host 0.0.0.0 --port 4020 --token dev-secret
bunx ora-worker serve --config .ora-worker/config.json
```
Worker endpoints:
- `GET /health`
- `GET /v1/providers`
- `GET /v1/providers/:provider`
- `GET /v1/providers/:provider/voices`
- `GET /v1/catalog`
- `GET /v1/voices`
- `GET /v1/cache`
- `GET /v1/cache/:cacheKey`
- `DELETE /v1/cache/:cacheKey`
- `POST /v1/audio/speech`
- `POST /v1/audio/speech/stream`
## Advanced playback APIs
The following are optional if your app needs live synchronization:
- `OraPlaybackTracker`
- `OraDocumentSession`
- `OraPlaybackOrchestrator`
These remain available for UI-driven reading or highlighting flows without being part of the core usage narrative.
## Examples
- `bun run example:openai` writes a sample speech file to `.ora-output/openai-article-sample.mp3`
- `bun run example:openai-document` exercises paragraph-first document synthesis
- `bun run example:orchestrator` prints multi-unit orchestration state
## Development
```bash
bun install
bun run setup:local
bun run test
bun run check
bun run build
bun run package:check
bun run docs:generate
bun run verify
```
The local gateway still serves the repo-backed fallback homepage while docs are generated and proxied in the existing scripts.