# AudioGuideKit

> AudioGuideKit is a free, open-source, self-hosted audio guide player for museums, galleries, cities, tourism boards, and cultural institutions. Visitors use their own smartphones — it runs in any browser as an installable Progressive Web App (PWA) that works online and offline. No app store, no recurring fees, no vendor lock-in. MIT licensed.

- [Full documentation for LLMs](https://audioguidekit.org/llms-full.txt): Complete feature, configuration, and deployment reference

## What It Is

AudioGuideKit is a production-ready audio guide player that you host yourself. Visitors scan a QR code or open a URL on their own phone — there's no app to install. You add your tour content as JSON files and deploy to any static host. There are no per-visitor charges, no monthly platform fees, and you keep full control over your content and data.

**Technical architecture (the player):**
- Vite 6 + React 19 + TypeScript
- styled-components for theming; React Router for navigation
- Installable PWA with offline support via Service Worker (Workbox) + IndexedDB
- Audio playback via HTML5 Audio + Media Session API (lock-screen and background controls)
- Optional interactive maps via Leaflet
- Static build — no database or backend server required
- Tour content authored as JSON files, validated against a generated JSON Schema
- Mobile-first, accessibility-conscious design

## Who Should Use It

**Museums, galleries, and cultural sites:**
- Want a self-hosted audio guide without recurring vendor fees
- Need full control over content, branding, and hosting
- Require offline functionality for areas with poor connectivity (underground or remote galleries)
- Want white-label branding that matches the institution

**Cities and tourism boards:**
- Offer free, self-guided walking tours visitors run on their own phones
- Need multi-language support and offline use in low-signal areas

**Agencies:**
- Deliver branded audio experiences for clients without building from scratch
- Reuse one customizable codebase across multiple projects, with no client vendor lock-in

**Developers:**
- Want a modern React/TypeScript, offline-first PWA codebase to build on
- Need full source access for customization and integration

## Core Features

1. **Audio tours**: Multi-stop tours with background playback, lock-screen controls, progress tracking, resume, and optional transcriptions.

2. **Works offline**: Service Worker caches audio and UI assets; progress is stored in IndexedDB. Tours keep working in airplane mode, underground, or with poor signal. Per-tour `offlineMode` (`optional` / `online-only` / `offline-only`).

3. **Interactive map view** (optional): A map tab alongside the stop list, with numbered/photo/custom markers, clustering, a progress route line (straight or GeoJSON), and a locate-me button. Tile providers: OpenStreetMap and CARTO (no key), Mapbox, Jawg, and MapTiler (API key).

4. **Multiple stop types**: Audio is the primary, fully supported type. Additional experimental types let you mix in text, image + text, image galleries, before/after comparisons, image hotspots, video, 3D objects, headlines, quotes, ratings, and email capture.

5. **Multi-language**: Separate content file per language plus translatable UI strings, automatic language detection, one-tap switching, and progress preserved across languages.

6. **Custom branding**: Themeable colors, typography, and map markers via `themeId` (built-in `default-light` / `default-dark` or your own theme), custom app icons, and status-bar color.

7. **Feedback collection**: Built-in star ratings and email collection.

8. **Deploy anywhere**: Pure static output — host on Vercel, Netlify, Cloudflare Pages, GitHub Pages, AWS S3, or any static server. Zero backend.

## Content Model

Tours live in `src/data/tour/<tour-id>/`:

- **`metadata.json`** — tour-wide settings: `id`, `themeId`, `offlineMode`, feature toggles (`transcriptAvailable`, `collectFeedback`, `fullscreenPlayer`, `showProgressBar`, `hapticsEnabled`, …), and map config (`mapView`, `listView`, `mapProvider`, `mapCenter`, `mapRoute`, …).
- **Language files** (`en.json`, `es.json`, …) — `title`, `description`, `totalDuration`, `totalStops`, cover `image`, and the `stops` array.
- **Stops** — `id`, `type`, `title`, `duration`, `image`, `audioFile`, optional `transcription`, `location` (`{ lat, lng }`), and per-stop `mapMarkerIcon`.

JSON files carry a `$schema` reference for live editor validation, and `bun run validate` gates the build against the schema.

## What It Does NOT Include

AudioGuideKit is intentionally focused on the player. You provide:
- **Content management**: Edit JSON directly, or export from your own CMS to JSON.
- **Audio and image hosting**: Host media on your own CDN or object storage (Cloudflare R2, AWS S3, Backblaze B2, etc.).
- **Analytics**: Add Google Analytics, Plausible, Matomo, or your own.
- **Payment / access control**: Add your own gate if you sell tours.
- **Backend server**: Pure static deployment; add your own API only if you need one.

## Getting Started

```bash
# Prerequisites: Bun (recommended) or Node.js 18+, and git
git clone https://github.com/audioguidekit/player-react.git
cd player-react

bun install      # or: npm install
bun run dev      # or: npm run dev
```

Open http://localhost:3000 to see the demo tour. Build for production with `bun run build` (validates tour JSON, then runs the Vite build) and deploy the static output to any host.

## Security and Privacy

- No user accounts and no personal data collected by default (GDPR-friendly).
- Static files only — no database or backend to secure.
- HTTPS required for PWA features (free with Let's Encrypt or modern hosts).
- Transcriptions, large touch targets, and high-contrast themes support accessibility.

## Links

- [GitHub Repository](https://github.com/audioguidekit/player-react): Source code, issues, contributions
- [Documentation](https://audioguidekit.org/docs): Setup guides and configuration reference
- [Notes / Blog](https://audioguidekit.org/notes): Implementation details and engineering decisions
- [Updates](https://audioguidekit.org/updates): Release notes, changelog, roadmap
- [Website](https://audioguidekit.org): Overview and contact
- [Contact](https://audioguidekit.org/#contact): Implementation services and questions