Skip to content
OxyHQPublic

About

Syra - Music platform by Oxy

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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.

syra.fm npm License MIT Expo SDK 57 React Native 0.86 TypeScript 5.9 Bun


What Syra is

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.

How it fits the Oxy platform

Identity and sessions come from oxy. Both apps mount one OxyProvider from @oxy.so/services, and every authenticated call goes through a single linked client built with @oxy.so/core, never a per screen token header. The interface is Bloom.

Syra also gives something back to the ecosystem. @syra.fm/sdk ships the live rooms engine that powers audio rooms in Mention, and a headless catalogue client anyone can read the public API with.

Workspaces

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

Quick start

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 workspace

Or start one at a time:

bun run dev:frontend
bun run dev:studio
bun run dev:backend

The 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 android
Builds, 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 clean

The backend also carries operational scripts, run from its own workspace: ensure-indexes, seed:music, migrate:catalog-entities, backfill:fingerprints and reseed:persons.

Using the SDK

@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/sdk
import { 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.

Architecture notes

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.

Documentation

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.

Contributing

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.

License

MIT. See LICENSE.

About

Syra - Music platform by Oxy

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages