🎵 SnapieAudioPlayer

Lightweight HTML5 audio player for voice messages and audio content on the 3speak/Snapie ecosystem. Features waveform visualization using WaveSurfer.js and IPFS content delivery.

✨ Features

• 🎨 WhatsApp/Discord-style UI - Clean, mobile-first interface
• 📊 Waveform Visualization - Interactive audio scrubbing with WaveSurfer.js
• ⚡ IPFS-powered - Decentralized audio storage with automatic gateway fallback
• 🔗 Dual Access Modes - Support for both permlinks (database) and direct CID playback
• 📱 Mobile-optimized - Touch controls, responsive design
• ⏩ Speed Control - 1x, 1.5x, 2x playback speeds
• 📈 Play Tracking - MongoDB-based analytics and engagement metrics
• 🔒 Rate-limited - Protection against API abuse
• 🎵 Content Categories - Distinguish between ephemeral voice messages and permanent content (podcasts, songs, interviews)
• 🖼️ Thumbnail Support - Optional cover art/artwork URLs for audio entries
• 📡 Feed API - Public endpoints for building discovery feeds, trending pages, tag browsing, and user profiles
• 🏷️ Tag System - Content tagging for discovery and filtering

🏗️ Architecture

Player (Frontend) ──→ Express API ──→ MongoDB ──→ IPFS Network
   ↓                      ↓              ↓            ↓
WaveSurfer.js        Audio Routes   Metadata    Audio Files
HTML5 Audio          Controllers    Schema      (CID-based)

📋 Prerequisites

• Node.js v16+ and npm
• MongoDB v5+ (local or remote)
• IPFS Gateway access (defaults to ipfs.3speak.tv)

🚀 Quick Start

1. Clone and Install

git clone <repository-url>
cd snapieaudio
npm install

2. Configure Environment

cp .env.example .env

Edit .env with your settings:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/snapieaudio
IPFS_PRIMARY_GATEWAY=https://ipfs.3speak.tv/ipfs/

3. Start Server

# Development mode (with nodemon)
npm run dev

# Production mode
npm start

4. Test Player

Open your browser:

# Direct CID playback (no database needed)
http://localhost:3000/play?cid=bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabq...

# Permlink-based playback (requires database entry)
http://localhost:3000/play?a=dkojohs

📁 Project Structure

snapieaudio/
├── src/                      # Frontend audio player
│   ├── index.html           # Player page template
│   ├── audio-player.js      # Player logic (WaveSurfer)
│   └── audio-styles.css     # Player styling
├── server/                   # Backend API
│   ├── index.js             # Express server
│   ├── routes/
│   │   └── audio.js         # Audio API routes
│   ├── controllers/
│   │   └── audioController.js
│   └── models/
│       └── AudioMessage.js  # MongoDB schema
├── assets/                   # Static assets (icons, etc.)
├── docs/                     # Internal documentation (gitignored)
│   └── AUDIO_PLAYER_DESIGN.md
├── package.json
└── .env.example

🔌 API Endpoints

Get Audio Metadata

GET /api/audio?a=dkojohs
GET /api/audio?cid=bafybeig...

Response:
{
  "permlink": "dkojohs",
  "author": "meno",
  "cid": "bafybeigdyrzt5...",
  "category": "voice_message",
  "duration": 45,
  "format": "mp3",
  "waveform": [0.2, 0.5, 0.8, ...],
  "title": "My Audio",
  "description": "This is an example audio recording",
  "tags": ["music", "podcast", "interview"],
  "thumbnail_url": "https://files.hive.blog/file/hiveimages/cover.jpg",
  "post_permlink": "my-audio-snap-2026",
  "audioUrl": "https://ipfs.3speak.tv/ipfs/bafy...",
  "audioUrlFallback": "https://dweb.link/ipfs/bafy...",
  "plays": 150
}

Get Audio Feed

GET /api/audio/feed?limit=20&offset=0&sort=newest

Query Parameters:
- limit: Items per page (default 20, max 100)
- offset: Pagination offset (default 0)
- sort: newest|oldest|plays|trending (default newest)
- category: voice_message|podcast|song|interview|audiobook|noise_sample
- tag: Filter by tag (e.g., "music")
- owner: Filter by username

Response:
{
  "items": [
    {
      "permlink": "abc123xy",
      "owner": "meno",
      "audio_cid": "QmdMsEX...",
      "category": "podcast",
      "duration": 1800,
      "format": "mp3",
      "title": "My Podcast",
      "tags": ["podcast", "tech"],
      "thumbnail_url": "https://...",
      "plays": 152,
      "createdAt": "2026-02-20T10:30:00Z",
      "audioUrl": "https://ipfs.3speak.tv/ipfs/...",
      ...
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 156,
    "hasMore": true
  }
}

Examples:
GET /api/audio/feed?sort=plays              # Trending audio
GET /api/audio/feed?category=podcast        # All podcasts
GET /api/audio/feed?tag=music&sort=plays    # Trending music
GET /api/audio/feed?owner=meno              # User's audio

Track Play Count

POST /api/audio/play
Content-Type: application/json

{
  "permlink": "dkojohs"
}

Response:
{
  "success": true,
  "plays": 151
}

📊 MongoDB Schema

{
  permlink: "dkojohs",        // Unique 8-char ID
  author: "meno",
  cid: "bafybeigdyrzt5...",  // IPFS CID
  category: "voice_message",  // Content type: voice_message, podcast, song, interview, audiobook, noise_sample
  duration: 45,               // Seconds
  format: "mp3",
  title: "My Audio",
  description: "This is an example audio recording",
  tags: ["music", "podcast"],  // Array of content discovery tags
  thumbnail_url: "https://files.hive.blog/...",  // Optional cover art
  post_permlink: "my-audio-snap-2026",  // Optional blockchain post reference
  waveform: {
    peaks: [0.2, 0.5, ...],
    length: 100
  },
  plays: 150,
  created: ISODate("2025-11-26T10:30:00Z"),
  status: "active"
}

🎨 Usage Examples

Embed in HTML

<iframe 
  src="https://audio.3speak.tv/play?a=dkojohs" 
  width="600" 
  height="100" 
  frameborder="0">
</iframe>

React Component

const AudioMessage = ({ permlink }) => (
  <iframe 
    src={`https://audio.3speak.tv/play?a=${permlink}`}
    style={{ border: 'none', width: '100%', height: '100px' }}
    allow="autoplay"
  />
);

🛠️ Development

Available Scripts

npm start      # Start production server
npm run dev    # Start development server with nodemon
npm test       # Run tests (to be implemented)

Adding Test Data

Create a sample audio entry in MongoDB:

db.audio_messages.insertOne({
  permlink: "testaud1",
  author: "testuser",
  cid: "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabq...",
  duration: 45,
  format: "mp3",
  bitrate: 128,
  waveform: { peaks: Array(100).fill(0).map(() => Math.random()), length: 100 },
  title: "Test Audio",
  plays: 0,
  created: new Date(),
  status: "active",
  visibility: "public"
});

Test it:

http://localhost:3000/play?a=testaud1

🔧 Configuration

Environment Variables

Variable	Default	Description
PORT	3000	Server port
MONGODB_URI	mongodb://localhost:27017	MongoDB connection
DB_NAME	snapieaudio	Database name
IPFS_PRIMARY_GATEWAY	ipfs.3speak.tv/ipfs/	Primary IPFS gateway
IPFS_FALLBACK_GATEWAY_1	dweb.link/ipfs/	Fallback gateway #1
IPFS_FALLBACK_GATEWAY_2	cloudflare-ipfs.com/ipfs/	Fallback gateway #2
RATE_LIMIT_WINDOW_MS	60000	Rate limit window
RATE_LIMIT_MAX_REQUESTS	100	Max requests per window

MongoDB Indexes

Indexes are automatically created on startup:

db.audio_messages.createIndex({ permlink: 1 }, { unique: true })
db.audio_messages.createIndex({ author: 1, created: -1 })
db.audio_messages.createIndex({ cid: 1 })
db.audio_messages.createIndex({ created: -1 })

🌐 Live Pages

• Landing Page: https://audio.3speak.tv/ - Project overview and features
• Demo Upload: https://audio.3speak.tv/demo - Try uploading audio (24h expiry)
• Admin Panel: https://audio.3speak.tv/admin - Storage management (password protected)
• Player: https://audio.3speak.tv/play?a=PERMLINK - Audio playback

🚦 Roadmap

Phase 1: MVP ✅

• Basic player with WaveSurfer.js
• MongoDB schema & API endpoints
• CID-based playback
• IPFS gateway fallback
• Play tracking

Phase 2: Upload System ✅

• Audio upload endpoint with API key auth
• IPFS pinning (local node)
• Permlink auto-generation
• File validation & processing
• Demo upload page
• Admin storage management panel

Phase 3: Enhancement

• Speed control UI
• Download functionality
• Share buttons
• Mobile app integration

Phase 4: Integration

• React component library
• Snapie chat integration
• Hive blockchain support
• Podcast RSS feeds

🐛 Troubleshooting

Player won't load audio

1. Check IPFS gateway is accessible:

   curl https://ipfs.3speak.tv/ipfs/<your-cid>

2. Verify MongoDB connection:

   mongosh mongodb://localhost:27017/snapieaudio
   db.audio_messages.find()

3. Check browser console for errors

CORS issues

If embedding in external sites, update CORS settings in server/index.js:

app.use(cors({
  origin: ['https://yourdomain.com'],
  credentials: true
}));

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Related Projects

• WaveSurfer.js - Audio waveform visualization
• 3speak - Decentralized video platform
• IPFS - Distributed file system

📧 Contact

For questions or support, reach out to the 3speak/Snapie team.

---

Built with ❤️ for the 3speak/Snapie ecosystem