A mobile-first lightweight audio guide player built in React for the web. Runs online and offline as a PWA, self-hosted by default, with easy customization via themes.
Live demo · Documentation · GitHub
- Audio tours — 13 stop types: audio, video, text, image gallery, before/after slider, hotspots, 3D objects, embeds, and more
- Progress tracking — Application-wide progress tracking with deep linking to specific stops
- Offline support — Full PWA with Service Worker caching and Media Session API support
- Multiple languages — Automatic language detection, seamless switching, localized UI (English, German, French, Italian, Spanish, Czech)
- Layout options — List, thumbnail row, or large image cards; optional fullscreen player
- Interactive map — Optional map tab with GPS stop markers, clustering, and multiple tile providers
- Theming — Fully customizable themes: colors, typography, markers, and more
# Clone the repository
git clone https://github.com/audioguidekit/player-react.git
cd player-react
# Install dependencies
bun install
# Start development server
bun run dev| Guide | Description |
|---|---|
| Adding tours | Tour setup: metadata.json fields, file structure, display options, validation |
| Stop types | All 13 stop types with required/optional fields and JSON examples |
| Languages | Multi-language setup, selection order, adding new languages |
| Map view | Interactive map tab: tile providers, GPS markers, clustering |
| Themes | Full ThemeConfig reference and how to create a custom theme |
| PWA | App icons: file list, regeneration, manifest |
| Testing | Playwright end-to-end tests: commands, test files, writing tests |
bun run dev # Development server (port 3000)
bun run build # Production build
bun run preview # Preview production build
bun run test # Run Playwright tests- React 19 with TypeScript
- Vite 6 for builds
- Framer Motion for animations
- Styled Components + Tailwind
- Phosphor Icons
- Workbox for PWA/Service Worker
player-react/
├── screens/ # TourStart, TourDetail, FullscreenPlayer
├── components/
│ ├── feed/ # Stop cards (Audio, Video, Text, 3D, etc.)
│ ├── sheets/ # Bottom sheets (Rating, Language, TourComplete)
│ └── player/ # Audio player components
├── hooks/ # useAudioPlayer, useProgressTracking, useDeepLink, etc.
├── context/ # React context providers
├── src/
│ ├── services/ # Data loading, IndexedDB, storage
│ ├── theme/ # Theme system
│ ├── translations/ # UI translations
│ └── data/tour/ # Tour JSON files
├── tests/ # Playwright e2e tests
├── types.ts # Shared TypeScript types
└── docs/ # Documentation
Tours are JSON files in /src/data/tour/:
src/data/tour/
├── metadata.json # Shared config (theme, offline mode)
├── en.json # English content
├── de.json # German content
└── fr.json # Add as many as needed
See Adding Tours for the complete guide.
MIT
- GitHub Organization
- llms.txt — for AI assistants