First run

With the development server running (bun run dev), let's take a tour of the tour player. This will help you understand what visitors will experience and how the different features work.

The start screen

When you first open http://localhost:3000, you'll see the guide start screen with:

• A hero image that sets the mood for the tour. This is the image field in your tour file.
• Guide title, short description and duration. Keep this engaging—it's your pitch!
• A "Start" button that begins the tour and loads the first stop.

The guide detail

After starting the tour, you'll see a scrollable feed of "stops." Each stop is a card that can contain:

• Audio content with playback controls
• Images with optional duration badges
• Text for written content
• Videos for multimedia stops
• And more (quotes, ratings, 3D objects...)

Try playing audio

Tap on an audio stop card. Notice:

1. The mini player appears at the bottom of the screen
2. Lock screen controls work (try locking your phone while playing)
3. Progress is saved automatically—close the browser and reopen to resume

The mini player

The mini player is the floating control bar at the bottom. It has two states:

Default state

This is a standard player with:

• Track title and progress bar shown around the main play/pause button
• Skip forward/backward buttons (15 seconds)
• Transcription toggle (if transcripts are available)

You can swipe left/right to skip to the next/previous stop

Minimized state

When you drag the player down, it collapses to a compact bar. Audio keeps playing!

Progress tracking

AudioGuideKit automatically tracks visitor progress:

• Overall progress in the header shows how much is left to listen
• Completed stops show a checkmark on each stop

Progress persists across page refreshes and browser sessions and current position is always saved (even the exact second within an audio track).

Try this experiment:

1. Start playing audio
2. Close the browser tab
3. Reopen http://localhost:3000
4. Your progress should be exactly where you left it!

Offline mode

By default, each guide has two buttons on the main screen:

1. Start tour
2. Download for offline

This setup can be chaned easily and there are in total three options:

• online and offline (default) - Visitors can choose to download. Great for most use cases.
• offline only - Download is required before playback. Use for locations with no connectivity.
• online only - No download option. For tours with frequently updated content.

Language switching

If your tour has multiple languages, visitors can switch anytime:

1. Tap the language flag in the header
2. Select a new language from the sheet
3. Tour reloads in the new language
4. Progress is preserved—same stop, same position!

Many audio tour apps lose your place when switching languages. We don't.

Responsive design

Try resizing your browser window or opening on different devices. AudioGuideKit is mobile-first but works beautifully on tablets and desktops too.

The layout adapts with:

• Mobile: Full-screen cards, bottom mini player
• Tablet: Slightly larger cards, more breathing room
• Desktop: Centered content with max-width constraint

Quick commands reference

While developing, you'll use these commands:

# Start development server
bun run dev
 
# Build for production
bun run build
 
# Preview production build locally
bun run preview
 
# Run tests
bun run test