Songloft Player (Lynx)

A ReactLynx + TypeScript rewrite of the Songloft Flutter client, targeting Android, iOS, HarmonyOS, and Web.

Learn about the underlying technology: Lynx official website · ReactLynx documentation.

Current status

This is a preview client. Playback, library/playlists, lyrics, plugins, themes, multiple servers, and administrative settings are implemented. About now separates client checks from server upgrades: dev checks only dev, while stable checks only the latest stable release. All three native bundle updaters are integrated in source; Android has local UI download/cancel/cold-start evidence, while iOS/HarmonyOS compilation and device acceptance remain open. Production update signing is unconfigured. Older shells and incompatible updates provide same-channel installation links; see Client updates. Native desktop clients and a bundled local backend remain outside this work.

Native device caching now has identity/track-variant indexes, whole-playlist/selection tasks and local management/offline playback. Authentication expiry preserves local-only access; explicit logout hides the previous identity. See Device cache. Android has real-file/UI evidence; iOS/HarmonyOS compilation and device acceptance remain open.

Web supports playlist JSON import/export with file selection, authenticated refresh, downloads and cancellation. Expired browser activation falls back to main-thread controls. Chrome standalone and root-path embedded flows were exercised; Firefox/Safari remain unverified. See Web deployment.

Web playback settings also provide a persisted keyboard-shortcut switch: Space toggles playback and Ctrl/⌘ + arrows change tracks or volume. See Shortcuts for input/overlay/plugin focus protection and the Chrome validation scope.

Platform	Release artifact	Limitations
Android 5.0+	Release-signed APK	Background playback, notifications, and DLNA still need ongoing device regression testing
iOS 15+	Unsigned IPA	Re-sign before installation; Live Activity requires iOS 16.2+
HarmonyOS NEXT / API 13+	Signed HAP	Experimental; video module and XComponent surface exist, but compilation and device behavior need verification
Web	Standalone / embedded archives	No bundled backend, DLNA, or per-song offline cache; browser compatibility requires actual testing

Installation and downloads

• Stable releases: published from version tags.
• Development release: automatically built after code pushes to main; updated only when every platform succeeds.
• Installation guide: package names, signing requirements, server connections, and checksums.
• 简体中文

Download assets published in GitHub Releases; the four-platform CI updates dev only after all five packages build and pass verification. Maintainers of a fork must configure signing secrets; see the release guide.

Technology stack

Layer	Implementation
Build/framework	Rspeedy + ReactLynx + TypeScript
State	Zustand for client state; TanStack Query for server data
Routing	TanStack Router, memory history and code-based routes
UI	Individual lynx-ui packages, Apple semantic design tokens (src/shared/theme/tokens.css), and @lynx-js/motion
Models	zod with snake_case → camelCase transforms
Localization	i18next + react-i18next (English / Chinese)
Tests	Vitest + @testing-library for unit tests; TestBridge + Vitest for E2E
Native	Ten custom modules covered by contract gates: Audio/Storage/Platform/Dlna/Video/SongCache/Navigation/PluginBridge, Android FloatingLyric, and iOS LiveActivity
Web	@lynx-js/web-core renders the bundle in a browser <lynx-view>

Quick start

Requires Node ^20.19 || >=22.12, pnpm, and a Songloft backend at http://localhost:58091 (initial credentials: admin/admin).

pnpm install
pnpm run web:sync && pnpm run web:dev

Validation commands:

pnpm run build        # Must emit both File (lynx) and File (web)
pnpm run typecheck    # tsc -b; --noEmit alone does not check this project
pnpm test            # Unit tests and contract gates
pnpm run test:release # Release tooling and actual Web output (build first)

These checks cover JS and release tooling. They do not replace Swift/Kotlin/ArkTS compilation or browser rendering. Changes to a host require its platform checks.

Getting started (Chinese) · Build and run

Project structure

src/              Client source
  core/           Networking, storage, configuration
  features/       auth/home/library/library-ops/player/playlist/settings/jsplugin
  models/         zod models
  native/         TypeScript native facades
  shared/         Components, themes, layouts, navigation
  store/          Zustand state
  i18n/           English / Chinese
android/          Kotlin host and native modules
ios/              Swift host and native modules
harmony/          ArkTS host and native modules
web/              Web host and static development server
demo-frame-plugin/ Native Lynx plugin example
e2e/              Drivers and cross-platform scenarios
scripts/          Build, release, and localization tooling
patches/          Committed upstream patches
docs/             Documentation

Documentation

Documentation index organizes tutorials, how-to guides, references, explanations, project tracking, and archives.

Task	Reference
Start from scratch	Getting started (Chinese)
Build a platform	Build and run
Write/run tests	Testing
Add native capabilities	Native development · Module contracts
Look up conventions	API and stores · Back navigation
Understand runtime behavior	Lynx constraints · Debugging
Take over development	Handoff

Root-level references:

• AGENTS.md: development constraints and validation rules.
• ARCHITECTURE.md: architecture overview; detailed explanations live in docs/architecture/.
• HARNESS.md: build and validation entry points and their coverage.
• DESIGN.md: Apple HIG, materials, Liquid Glass, and implementation notes.

The backend OpenAPI contract lives in the backend repository's docs/swagger.json, or at http://localhost:58091/swagger/index.html on a development server.

Status

Current delivery status and outstanding validation are maintained in the handoff. Historical batches are in progress (Chinese); platform capabilities are in the platform reference (Chinese). This README avoids duplicating test counts, artifact sizes, and dated validation snapshots.

Releases and contributing

./scripts/bump-version.sh patch --dry-run
./scripts/bump-version.sh patch

The script synchronizes versions, commits to main, creates a v* tag, and pushes. The equivalent pnpm run release patch remains available; the shell entry delegates to the existing Node release logic and supports the same arguments. See the release guide and CONTRIBUTING.en.md.

Version history is maintained in the Chinese-only root CHANGELOG.md, updated after a versioned release succeeds. Rolling dev commit history remains on its release page.

License

Apache-2.0, matching the Songloft backend and Flutter client. Dependencies retain their own licenses.