Skip to main content

Phase 2: QR Codes & Audio Playback

Timeline: Weeks 7-8 Status: Planned

Core Goal​

Generate QR codes for completed requests and enhance the existing /play/{slug} page with social sharing features.

New Features​

QR Code Generation​

  • Automatic creation on request completion
  • High-contrast accessibility options
  • Multiple format downloads (PNG, SVG, PDF)
  • Custom branding integration
  • Multiple size variants

Enhanced Playback Page (/play/{slug})​

  • Add social sharing buttons (Twitter, Facebook, LinkedIn)
  • Copy link functionality
  • Open Graph meta tags for social previews
  • Enhanced mobile experience
  • Client branding display (if provided)
  • Builds on Phase 1's basic playback page

Download Management​

  • QR code file downloads
  • Multiple format options
  • Batch download capability
  • Print-optimized versions

Enhanced Workflows​

Complete Request Flow​

QR Generation Flow​

Acceptance Criteria​

F2.1 - QR Code Generation​

User Story: As system, I want automatic QR generation when requests complete.

Acceptance Criteria:

  • AC2.1.1: Given admin uploads audio, when status "completed", then QR generated within 30 seconds
  • AC2.1.2: Given QR generated, when scanned, then directs to existing playback page (/play/{slug})
  • AC2.1.3: Given QR generation fails, when error occurs, then admin alerted with manual option
  • AC2.1.4: Given client needs formats, when accessing completed request, then PNG, SVG, PDF available
  • AC2.1.5: Given accessibility needs, when QR generated, then high-contrast version created automatically
  • AC2.1.6: Given client downloads QR, when downloaded, then filename includes request ID and timestamp
  • AC2.1.7: Given download requested, when accessed, then file served within 2 seconds

F2.2 - Enhanced Playback Page​

User Story: As anyone sharing audio content, I want social sharing features to promote my content.

Acceptance Criteria:

  • AC2.2.1: Given I'm on /play/{slug}, when page loads, then social sharing buttons visible (Twitter, Facebook, LinkedIn)
  • AC2.2.2: Given I click Twitter share, when clicked, then opens Twitter with pre-filled message and link
  • AC2.2.3: Given I click Facebook share, when clicked, then opens Facebook share dialog with Open Graph preview
  • AC2.2.4: Given I click LinkedIn share, when clicked, then opens LinkedIn share with professional preview
  • AC2.2.5: Given I want to copy link, when I click copy button, then link copied to clipboard and confirmation shown
  • AC2.2.6: Given page is shared on social media, when previewed, then Open Graph meta tags show title, description, and image
  • AC2.2.7: Given client provided website URL, when I view page, then "Learn More" button links to client website
  • AC2.2.8: Given client provided social links, when I view page, then client's social media icons displayed
  • AC2.2.9: Given I access page via QR code, when scanned, then page loads with all social features visible
  • AC2.2.10: Given mobile device, when I share, then native mobile share dialog available as option

F2.3 - Download Management​

User Story: As client, I want to download QR codes in multiple formats.

Acceptance Criteria:

  • AC2.3.1: Given completed request, when I view details, then download section shows PNG, SVG, PDF options
  • AC2.3.2: Given I click PNG, when generated, then high-resolution PNG suitable for print (300 DPI min)
  • AC2.3.3: Given I click SVG, when generated, then scalable vector for large format printing
  • AC2.3.4: Given I click PDF, when generated, then print-ready PDF with crop marks/bleed
  • AC2.3.5: Given I need custom size, when I access options, then specify dimensions (1-20 inch range)
  • AC2.3.6: Given I download, when complete, then filename clearly identifies content (name_micdots_date)
  • AC2.3.7: Given multiple downloads, when I access, then can redownload any format anytime
  • AC2.3.8: Given download fails, when error occurs, then clear error message and retry option

Technical Requirements​

QR Code Service Integration​

  • QR Tiger API integration
  • Multiple format generation
  • Custom branding overlay
  • Error correction level configuration

Playback Page​

  • SEO-optimized metadata
  • Open Graph tags for social sharing
  • Responsive audio player
  • Accessibility features (WCAG AA)

File Management​

  • Organize QR files by request
  • CDN delivery optimization
  • Download tracking
  • Storage cleanup policies

QR Code Specifications​

Format Options​

FormatUse CaseResolution
PNGDigital sharing1000x1000px
SVGScalable printingVector
PDFPrint-readyA4/Letter

Accessibility Features​

  • High contrast mode (black/white)
  • Enhanced quiet zone
  • Error correction level: H (30%)
  • Minimum size: 2cm x 2cm
QR Code Research

Standard QR codes selected over micro QR codes for compatibility with blind-assisted devices and Google Pixel.

Playback Page Features​

Audio Player​

  • Standard HTML5 audio controls
  • Keyboard navigation support
  • Screen reader compatible
  • Volume control
  • Progress bar

Page Elements​

  • Brand logo
  • Client attribution (optional)
  • Social sharing buttons
  • Download QR button
  • Analytics tracking

Responsive Design​

  • Mobile-first audio player with touch-friendly controls
  • Download and share buttons with clear labels
  • Accessible audio controls with ARIA labels
  • Fallback message for unsupported browsers

Testing Requirements​

QR Code Testing​

# Test QR generation endpoint
curl -X POST http://localhost:5000/api/v1/qr/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -d '{
    "requestId": "uuid",
    "url": "https://micdots.com/slug",
    "formats": ["png", "svg", "pdf"]
  }'

Expected Response:

{
  "success": true,
  "data": {
    "qrCodeId": "uuid",
    "files": {
      "png": "https://cdn.micdots.com/qr/uuid.png",
      "svg": "https://cdn.micdots.com/qr/uuid.svg",
      "pdf": "https://cdn.micdots.com/qr/uuid.pdf"
    }
  }
}

Playback Page Testing​

  • Mobile device compatibility
  • Screen reader navigation
  • Social sharing validation
  • Audio format support
  • Load time performance

Success Criteria​

Functionality​

  • ✅ QR codes generated automatically
  • ✅ Multiple formats available
  • ✅ Playback page accessible publicly
  • ✅ Audio plays correctly
  • ✅ Download links work

Performance​

  • QR generation < 5 seconds
  • Playback page load < 2 seconds
  • Audio streaming starts < 1 second

Quality​

  • QR codes scan reliably
  • High contrast options available
  • Audio playback smooth
  • Mobile responsive design

Deliverables​

  1. QR Generation System

    • QR Tiger API integration
    • PNG, SVG, PDF format generation
    • High-contrast variants
    • Storage management

  2. Enhanced Playback Page

    • Social sharing buttons
    • Open Graph meta tags
    • Copy link functionality
    • Client branding display

  3. Client Downloads

    • QR code download interface
    • Multi-format selection
    • Batch download operations

  4. Documentation

    • QR code usage guide
    • Social sharing best practices
    • API documentation

Next Phase​

➡️ Phase 3: Voice Management System