Syra is a music and podcast platform for iOS, Android and the web.
Artists upload their own work, listeners stream it, and live audio rooms run on top of the same catalogue.
|
An own catalogue platform. Every track is Syra hosted, and music enters through exactly one path: a creator uploads it, the backend transcodes it to HLS, and it becomes playable. There is no external ingest, no import service and no provider reconciliation. That single path is what makes the rules simple. A track is playable if it is available and has not been removed for copyright, one predicate that both the catalogue and the player ask, so a takedown can never stay listed and then fail at play. Podcasts are a separate vertical and do mirror external RSS. |
Identity and sessions come from oxy. Both apps mount one Syra also gives something back to the ecosystem. |
| Package | Path | What it holds |
|---|---|---|
@syra/frontend |
packages/frontend |
The listener app for iOS, Android and web: browse, search, library, playlists, albums, artists, podcasts, radio, live rooms and upload |
@syra/backend |
packages/backend |
Express 5 API and Socket.IO: catalogue, ingest and HLS transcoding, streaming entitlement, recommendations, copyright handling |
@syra/studio |
packages/studio |
The creator portal: register and upload music, run insights, manage podcast shows and episodes, go live |
@syra.fm/sdk |
packages/sdk |
The public SDK: a headless catalogue client plus the live rooms engine |
@syra/shared-types |
packages/shared-types |
The TypeScript DTOs the frontend, studio and backend all compile against |
You need Bun 1.3 or newer, Node.js 18 or newer, and a PostgreSQL instance
(docker compose -f docker-compose.postgres.yml up -d starts one locally).
bun install # also builds shared-types via postinstall
bun run dev # every workspaceOr start one at a time:
bun run dev:frontend
bun run dev:studio
bun run dev:backendThe frontend and studio are Expo apps. Run a specific target from their workspace:
bun run --cwd packages/frontend web
bun run --cwd packages/frontend ios
bun run --cwd packages/frontend androidBuilds, tests and lint
bun run build # every package
bun run build:shared-types
bun run build:sdk
bun run build:frontend
bun run build:studio
bun run build:backend
bun run test # every package
bun run lint # Biome (every package) + the Expo apps' minimal ESLint
bun run lint:fix # Biome safe fixes and formatting
bun run format # Biome formatter only
bun run cleanThe backend also carries operational scripts, run from its own workspace: ensure-indexes, seed:music, migrate:catalog-entities, backfill:fingerprints and reseed:persons.
@syra.fm/sdk is one flat package that resolves per platform through export conditions, so a Node consumer never installs React Native or LiveKit.
bun add @syra.fm/sdkimport { createSyraClient } from '@syra.fm/sdk';
const syra = createSyraClient(); // defaults to https://api.syra.fm
const page = await syra.searchTracks('lofi beats', { limit: 10 });
const track = await syra.getTrack(page.items[0].id);
const preview = syra.previewUrl(track.id); // a directly playable 30 second MP3
const cover = syra.artworkUrl(track, 'large');On Node and in bundlers you get the headless catalogue client: public reads only, no React, no DOM, with zod as the single runtime dependency. On React Native through Metro and on Expo web you additionally get the live rooms engine, audio rooms over LiveKit, and the SyraIcon brand mark. Its React Native, LiveKit and Expo dependencies are optional peers, so headless consumers never pull them in.
Full reference in the SDK README.
|
State ownership in the apps TanStack Query owns server state: catalogue reads, library, playlists, artist profiles, preferences, recommendations and privacy. Zod validates responses at the service boundary. Zustand is reserved for local state only, player, queue and transient UI, and never mirrors data Query already owns. Identity sensitive queries wait for the Oxy cold boot to settle and keep separate cache keys for guest and signed in, so an anonymous startup response can never leak into a session. |
The backend is the authority Playback resolves through the stream resolver on the backend, which is the sole entitlement authority. Frontend preference state is never the source of truth for whether something may play. Containers follow the tracks. An album, artist, playlist, genre card or search result is not presented as playable when it holds no playable tracks, because the alternative is a listener tapping into an empty room. |
| Document | Covers |
|---|---|
| Documentation index | Everything below, in one place |
| Theme quick reference | Theming with Bloom and NativeWind |
| Theming troubleshooting | Common theming failures and their causes |
| Performance guide | Where the time goes and how to get it back |
| Runbooks | Ordered production steps, including the user upload rollout |
| Compliance | DMCA policy and the repeat infringer clause |
| Backend README | The API surface in detail |
| Frontend README | The app in detail |
Instructions for AI coding agents live in AGENTS.md.
Contributions are welcome, especially from people who make music and can tell us where the product gets an artist's needs wrong. Open an issue or a pull request, and run bun run test && bun run lint before you do. Org wide contributing notes, the security policy and the code of conduct live in the organisation profile.
MIT. See LICENSE.