Skip to main content

Audio Playback Page (Slug)

Overview​

This is the public audio playback page that loads when someone clicks a shareable link. It requires no authentication and is accessible to anyone with the unique slug URL.

URL Format: https://micdots.com/play/{slug}

Epic 1: Shareable links for audio playback

Related API: See Text-to-Speech Submission API for the backend endpoint that powers this page.

Key Features:

  • ✅ Public access with auto-play audio and minimal, distraction-free interface
  • ✅ Mobile-optimized, works on any device with a web browser

Live Preview​

Audio Playback Page (Public)
●Not Logged In

🎙️

MicDots Audio

Your audio is ready to play

0:080:23
▶️

Auto-play enabled: Audio will start automatically when you land on this page

Powered by MicDots

Text-to-Speech Audio QR Platform

API Endpoints​

This page uses the following API endpoint:

Get Submission by Slug (Public)​

Endpoint: GET /api/v1/play/{slug}

Description: Retrieves audio submission data by unique slug. This is a public endpoint that requires no authentication.

Path Parameters:

  • slug: string. Unique URL-safe identifier for the audio submission.

Response: Returns slug, audioUrl (S3 link), original text, and metadata. This data is used to populate the audio player and display information.

Page Characteristics​

Design Philosophy​

  • Minimal UI: Only essential controls, no distractions
  • Audio-First: Player is the primary focus
  • Mobile-Optimized: Large touch targets, readable on small screens
  • Fast Loading: Lightweight page for quick access

Visual Elements​

Page Layout

  • Branded header with logo, title, and subtitle
  • Audio player card with waveform, play/pause button, and progress bar
  • Auto-play notice banner
  • Footer with branding and platform description

User Experience Flow​

  1. User receives link from result page or QR code
  2. User clicks link or shares it (can be the QR code link too)
  3. Browser opens the playback page URL (/play/{slug})
  4. API fetches audio data from text-to-speech submission
  5. Page loads in 1-2 seconds
  6. Audio auto-plays immediately (if browser allows)
  7. User can control playback using on-screen controls

Epic 2 (QR Code - Future)​

  1. User scans QR code with their phone camera
  2. Browser opens the playback page URL (/play/{slug})
  3. Same experience as shareable link above

Data Flow​

This page is the final step in the text-to-speech submission flow:

  1. User submits text → TTS Submission Form
  2. Audio generated → Text-to-speech API creates audio and shareable link
  3. User receives link → Shareable URL returned immediately (can also be embedded in QR code)
  4. Link clicked/QR scanned → Opens this playback page (/play/{slug})
  5. Audio plays → User hears the generated audio

Data Retrieved:

{
  "slug": "happy-birthday-john",
  "audioUrl": "https://s3.amazonaws.com/micdots-audio/happy-birthday-john.mp3",
  "text": "Happy birthday John! Wishing you all the best on your special day.",
  "createdAt": "2024-01-22T14:30:00Z"
}

This data comes from the Text-to-Speech Submission created by the authenticated user.

Technical Behavior​

Page Load Flow​

  1. Fetch submission data from API endpoint: GET /api/v1/play/{slug}
    • Returns: slug, audioUrl, text, createdAt
  2. Load audio player with S3 URL from response
  3. Display text (optional - can show the original text)
  4. Auto-play audio if browser allows

Auto-Play Implementation​

Auto-play Rules:

  • Most mobile browsers allow auto-play after user interaction (QR scan)
  • Desktop browsers may require user click (show large play button)
  • Fallback: If auto-play is blocked, show prominent play button

Audio Source​

  • Audio file hosted on AWS S3 (from text-to-speech submission or custom upload)
  • Generated via ElevenLabs API or uploaded by user
  • Permanent storage (manual deletion feature coming in future)
  • Format: MP3 (widely supported)
  • Bitrate: Varies based on ElevenLabs output or original uploaded file quality

Mobile Considerations​

  • Responsive Design: Full viewport height, touch-friendly controls, works in portrait and landscape
  • Performance: Minimal JavaScript using native HTML5 audio, fast page load, works on slow connections

Access Control​

✅ Public Access - No Authentication Required

  • Anyone with the link can listen
  • No login or account needed
  • No rate limiting on playback
  • Shareable via any channel (SMS, email, social media)

Use Cases:

  • Restaurant menu item descriptions
  • Museum exhibit audio guides
  • Business card voice introductions
  • Product information at retail stores
  • Event announcements and schedules

URL Structure​

Format​

https://micdots.com/play/{slug}

Example​

https://micdots.com/play/happy-birthday-john

Properties​

  • Unique Slug: URL-safe identifier generated from text content
  • No Query Parameters: Clean URL for QR encoding (Epic 2)
  • Short & Scannable: Optimal for QR code size (Epic 2)
  • Human-Readable: Slug is descriptive and easier to share
  • Permanent Link: URL works indefinitely until manually deleted

API Endpoint​

The page fetches audio data from:

GET /api/v1/play/{slug}

See Text-to-Speech Submission API for technical details.

Browser Compatibility​

BrowserAuto-playControlsStatus
Chrome Mobile✅ Yes✅ FullSupported
Safari iOS✅ Yes*✅ FullSupported
Firefox Mobile✅ Yes✅ FullSupported
Chrome Desktop⚠️ May block✅ FullSupported
Safari Desktop⚠️ May block✅ FullSupported
Edge⚠️ May block✅ FullSupported

*iOS Safari allows auto-play after user gesture (QR scan counts)

Error Handling​

Submission Not Found (404)​

When GET /api/v1/play/{slug} returns 404, show error message:

"Audio not found or has been deleted.
Please contact the creator if you believe this is an error."

API Response:

{
  "success": false,
  "error": {
    "code": "SUBMISSION_NOT_FOUND",
    "message": "Submission with slug 'xxx' not found."
  }
}

Playback Error​

When audio file fails to load or play, show fallback message:

"Unable to play audio. Please check your internet connection and try again."

Browser Not Supported​

Show message for browsers without HTML5 audio support:

"Your browser doesn't support audio playback.
Please try opening this link in a modern browser."

API Service Error (500)​

When API is unavailable, show:

"Service temporarily unavailable. Please try again in a few moments."