📚 Developer Documentation

🚀 Getting Started

SnapieAudioPlayer provides a REST API for uploading, storing, and playing audio files on the decentralized IPFS network. All audio files are stored permanently on IPFS and metadata is indexed in our MongoDB database for fast retrieval.

Quick Start

1. Get an API key (contact 3speak team)
2. Upload audio via REST API
3. Embed player using returned permlink or CID
4. Track plays and engagement

🔐 Authentication

API keys are required for uploading audio. Include your API key in the request header:

X-API-Key: sk_your_api_key_here

📺 Embedding Player

Using iFrame

<!-- Embed by permlink -->
<iframe 
  src="https://audio.3speak.tv/play?a=abc123xyz"
  width="100%" 
  height="120"
  frameborder="0"
  allow="autoplay">
</iframe>

<!-- Embed by IPFS CID -->
<iframe 
  src="https://audio.3speak.tv/play?cid=QmdMsEXyDe5Z4S3n8THfYgFP1iH3ngCeCytdHnndzqdZAK"
  width="100%" 
  height="120"
  frameborder="0">
</iframe>

Display Modes

<iframe src="https://audio.3speak.tv/play?a=abc123&mode=minimal" height="80"></iframe>

Iframe Mode (No Scrollbars)

Add &iframe=1 for clean embedding without scrollbars - perfect for chat apps:

<!-- Clean embed with no scrollbars -->
<iframe 
  src="https://audio.3speak.tv/play?a=abc123&mode=compact&iframe=1"
  width="100%" 
  height="120"
  frameborder="0"
  scrolling="no"
  allow="autoplay">
</iframe>

📤 Upload API

Upload audio files to IPFS with metadata indexing.

Headers

Form Data Parameters

Response

{
  "success": true,
  "permlink": "w2ehm8pr",
  "cid": "QmdMsEXyDe5Z4S3n8THfYgFP1iH3ngCeCytdHnndzqdZAK",
  "playUrl": "https://audio.3speak.tv/play?a=w2ehm8pr",
  "apiUrl": "https://audio.3speak.tv/api/audio?a=w2ehm8pr"
}

▶️ Playback API

Retrieve audio metadata for playback. No authentication required.

Query Parameters

Response

{
  "permlink": "w2ehm8pr",
  "owner": "meno",
  "audio_cid": "QmdMsEXyDe5Z4S3n8THfYgFP1iH3ngCeCytdHnndzqdZAK",
  "duration": 45,
  "format": "mp3",
  "bitrate": 128,
  "sampleRate": 44100,
  "channels": 1,
  "waveform": {
    "peaks": [0.05, 0.34, 0.93, ...],
    "samples": 100
  },
  "audioUrl": "http://gateway.ipfs/ipfs/QmdMsEX...",
  "audioUrlFallback": "https://ipfs.io/ipfs/QmdMsEX...",
  "title": "My Audio",
  "plays": 42,
  "likes": 5,
  "createdAt": "2025-11-27T01:22:17.053Z"
}

Track Play Count

Increment play counter when audio starts playing.

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

{
  "permlink": "w2ehm8pr"
}

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

💻 Code Examples

JavaScript (Fetch API)

// Upload audio file
async function uploadAudio(file) {
  const formData = new FormData();
  formData.append('audio', file);
  formData.append('duration', 45);
  formData.append('format', 'mp3');
  formData.append('title', 'My Recording');

  const response = await fetch('https://audio.3speak.tv/api/audio/upload', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_your_api_key',
      'X-User': 'username'
    },
    body: formData
  });

  return await response.json();
}

// Get audio metadata
async function getAudio(permlink) {
  const response = await fetch(
    `https://audio.3speak.tv/api/audio?a=${permlink}`
  );
  return await response.json();
}

// Track play
async function trackPlay(permlink) {
  await fetch('https://audio.3speak.tv/api/audio/play', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ permlink })
  });
}

cURL

# Upload audio
curl -X POST https://audio.3speak.tv/api/audio/upload \
  -H "X-API-Key: sk_your_api_key" \
  -H "X-User: username" \
  -F "audio=@recording.mp3" \
  -F "duration=45" \
  -F "format=mp3" \
  -F "title=My Recording"

# Get metadata
curl "https://audio.3speak.tv/api/audio?a=w2ehm8pr"

# Track play
curl -X POST https://audio.3speak.tv/api/audio/play \
  -H "Content-Type: application/json" \
  -d '{"permlink":"w2ehm8pr"}'

Python

import requests

# Upload audio
def upload_audio(file_path, api_key):
    with open(file_path, 'rb') as f:
        files = {'audio': f}
        data = {
            'duration': 45,
            'format': 'mp3',
            'title': 'My Recording'
        }
        headers = {
            'X-API-Key': api_key,
            'X-User': 'username'
        }
        
        response = requests.post(
            'https://audio.3speak.tv/api/audio/upload',
            files=files,
            data=data,
            headers=headers
        )
        return response.json()

# Get metadata
def get_audio(permlink):
    response = requests.get(
        f'https://audio.3speak.tv/api/audio?a={permlink}'
    )
    return response.json()

⏱️ Rate Limits

❌ Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "Invalid file format",
  "message": "Allowed formats: mp3, m4a, ogg, webm, wav"
}

Common Errors

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

{
  "error": "File too large",
  "message": "Maximum file size is 50MB"
}

{
  "error": "Too many requests, please try again later"
}

{
  "error": "Upload not allowed",
  "message": "User is banned from uploading"
}

{
  "error": "Username required",
  "message": "X-User header must be provided for uploads"
}