Probe.dev API Documentation

Overview

HTTP Live Streaming (HLS) validation ensures your streams meet Apple’s technical specifications and work reliably across all Apple devices. Probe.dev provides Apple’s official MediaStreamValidator tool as a service, eliminating the need for local tool installation while providing comprehensive validation reports.

MediaStreamValidator is essential for App Store submissions, streaming service quality assurance, and debugging playback issues across iOS, macOS, and tvOS devices.

Why HLS Validation Matters

App Store Requirements

Mandatory for iOS Apps
Apple requires HLS compliance for video streaming apps

Rejection Prevention
Avoid App Store rejections due to streaming issues

Playback Quality

Universal Compatibility
Ensure streams work across all Apple devices

Error Prevention
Catch issues before they reach end users

Specification Compliance

RFC 8216 Standards
Validate against official HLS specifications

Future-Proofing
Ensure compatibility with upcoming iOS versions

Debugging Support

Detailed Error Reports
Identify specific compliance violations

Root Cause Analysis
Pinpoint encoding or packaging issues

Getting Started

Basic HLS Validation

Validate an HLS playlist for Apple compliance:

curl -G https://api.probe.dev/v1/probe/mediastreamvalidator \
  --data-urlencode "token=${PROBE_API_TOKEN}" \
  --data-urlencode "url=https://example.com/master.m3u8"

Quick Playlist-Only Check

For faster validation during development:

curl -G https://api.probe.dev/v1/probe/mediastreamvalidator \
  --data-urlencode "token=${PROBE_API_TOKEN}" \
  --data-urlencode "url=https://example.com/master.m3u8" \
  --data-urlencode "parse_playlist_only=true"

Use parse_playlist_only=true for rapid iteration during development. Switch to full validation before production deployment.

Comprehensive Validation

Full Stream Analysis

For production-ready validation including segment analysis:

curl -X POST https://api.probe.dev/v1/probe/mediastreamvalidator \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/master.m3u8",
    "parse_playlist_only": false,
    "enable_cli_output": true,
    "timeout": 650000,
    "inject_json": true
  }'

Parameter Configuration

Parameter	Purpose	Recommended Values
`parse_playlist_only`	Skip segment download/analysis	`true` for development, `false` for production
`enable_cli_output`	Include raw MediaStreamValidator output	`true` for debugging
`timeout`	Maximum analysis time (milliseconds)	`650000` (10+ minutes for large streams)
`inject_json`	Enhanced JSON formatting	`true` for easier parsing

Apple HLS Compliance Requirements

Essential Compliance Checks

MediaStreamValidator verifies these critical requirements:

Bitrate Ladder Requirements

Minimum Requirements:

At least 3 video quality levels for iOS apps
64 kbps audio-only variant required
Maximum 10 Mbps bitrate for cellular delivery

Recommended Structure:

Audio-only: 64 kbps
Low: 400-800 kbps
Medium: 1.2-2.5 Mbps
High: 3-6 Mbps
Premium: 8-10 Mbps (WiFi only)

Segment Duration Standards

Codec Requirements

Closed Caption Compliance

Common Validation Errors

Critical Issues

Bitrate Declaration Mismatch

Error: BANDWIDTH attribute doesn't match measured bitrate

Cause: Playlist declares different bitrate than actual stream

Solution:

# Re-encode with correct bitrate or update playlist
ffmpeg -i input.mp4 -b:v 2500k -maxrate 2750k -bufsize 5000k output.m3u8

Segment Duration Violations

Error: Segment duration exceeds target duration

Cause: Individual segments longer than #EXT-X-TARGETDURATION

Solution:

# Adjust segment duration during encoding
ffmpeg -i input.mp4 -hls_time 6 -hls_list_size 0 output.m3u8

Missing Audio-Only Variant

Error: No audio-only variant found

Cause: Required 64 kbps audio stream missing from master playlist

Solution:

# Create audio-only variant
ffmpeg -i input.mp4 -vn -acodec aac -b:a 64k audio_only.m3u8

Warning-Level Issues

Warnings:

Inefficient bitrate ladder gaps
Missing I-frame playlists
Suboptimal segment counts

Impact: Playback experience degradation

Integration Workflows

CI/CD Pipeline Integration

GitHub Actions Example

name: HLS Validation
on:
  push:
    paths: ['streams/**/*.m3u8']

jobs:
  validate-hls:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Validate HLS Streams
        run: |
          for playlist in streams/**/*.m3u8; do
            echo "Validating $playlist"
            response=$(curl -s -G https://api.probe.dev/v1/probe/mediastreamvalidator \
              --data-urlencode "token=${{ secrets.PROBE_API_TOKEN }}" \
              --data-urlencode "url=https://cdn.example.com/$playlist" \
              --data-urlencode "parse_playlist_only=true")
            
            if echo "$response" | jq -r '.success' | grep -q false; then
              echo "❌ Validation failed for $playlist"
              echo "$response" | jq -r '.error'
              exit 1
            else
              echo "✅ Validation passed for $playlist"
            fi
          done

Jenkins Pipeline

pipeline {
    agent any
    environment {
        PROBE_API_TOKEN = credentials('probe-api-token')
    }
    
    stages {
        stage('HLS Validation') {
            steps:
                script {
                    def playlists = sh(
                        script: "find streams/ -name '*.m3u8'",
                        returnStdout: true
                    ).trim().split('\n')
                    
                    playlists.each { playlist ->
                        def response = sh(
                            script: """
                                curl -s -G https://api.probe.dev/v1/probe/mediastreamvalidator \\
                                --data-urlencode "token=${PROBE_API_TOKEN}" \\
                                --data-urlencode "url=https://cdn.example.com/${playlist}"
                            """,
                            returnStdout: true
                        )
                        
                        def result = readJSON text: response
                        if (!result.success) {
                            error("HLS validation failed for ${playlist}: ${result.error}")
                        }
                    }
                }
            }
        }
    }
}

Pre-Publish Validation Script

#!/usr/bin/env python3
import requests
import sys
import time
from urllib.parse import urljoin

def validate_hls_stream(base_url, playlist_path, api_token):
    """Validate HLS stream before publishing"""
    
    full_url = urljoin(base_url, playlist_path)
    
    # Start validation
    response = requests.get(
        'https://api.probe.dev/v1/probe/mediastreamvalidator',
        params={
            'token': api_token,
            'url': full_url,
            'parse_playlist_only': False,
            'enable_cli_output': True
        }
    )
    
    if response.status_code != 200:
        print(f"❌ API Error: {response.status_code}")
        return False
    
    data = response.json()
    
    if not data.get('success', False):
        print(f"❌ Validation Failed: {data.get('error', 'Unknown error')}")
        if 'cli_output' in data:
            print("\nDetailed Output:")
            print(data['cli_output'])
        return False
    
    print(f"✅ Validation Passed: {playlist_path}")
    return True

if __name__ == "__main__":
    # Validate all streams before deployment
    streams = [
        "master.m3u8",
        "audio_only/playlist.m3u8",
        "video/720p/playlist.m3u8"
    ]
    
    base_url = "https://cdn.example.com/streams/"
    api_token = os.getenv('PROBE_API_TOKEN')
    
    all_passed = True
    for stream in streams:
        if not validate_hls_stream(base_url, stream, api_token):
            all_passed = False
    
    sys.exit(0 if all_passed else 1)

App Store Submission Workflow

Pre-Submission Checklist

Technical Validation

Device Testing

Accessibility Compliance

Documentation for App Review

Include MediaStreamValidator reports in your App Store submission:

# Generate comprehensive validation report
curl -X POST https://api.probe.dev/v1/probe/mediastreamvalidator \
  -H "Authorization: Bearer $PROBE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-cdn.com/master.m3u8",
    "parse_playlist_only": false,
    "enable_cli_output": true
  }' > hls_validation_report.json

Performance Optimization

Validation Speed Tips

Development Phase: Use parse_playlist_only=true
Staging Phase: Full validation with reasonable timeout
Production Phase: Validate representative samples
CI/CD: Parallel validation of multiple streams

Recommended Timeouts

Stream Type	Recommended Timeout	Reasoning
Short clips (< 5 min)	2-3 minutes	Quick analysis
Standard content (5-60 min)	5-8 minutes	Thorough checking
Long-form content (> 1 hour)	10-15 minutes	Complete validation
Live streams	3-5 minutes	Sample-based analysis

Troubleshooting

Common Issues and Solutions

Timeout Errors

Access Denied Errors

Incomplete Validation

Debugging with CLI Output

Enable detailed output for troubleshooting:

curl -X POST https://api.probe.dev/v1/probe/mediastreamvalidator \
  -H "Authorization: Bearer $PROBE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://problematic-stream.com/playlist.m3u8",
    "enable_cli_output": true,
    "parse_playlist_only": false
  }' | jq -r '.cli_output'

Best Practices

Development Workflow

Validate frequently during encoding
Use playlist-only validation for quick checks
Automate validation in build pipelines
Keep validation reports for debugging

Production Deployment

Full validation before CDN upload
Validate after CDN propagation
Monitor validation results over time
Document compliance for App Store

Performance

Cache validation results for unchanged content
Validate samples of long-form content
Use appropriate timeouts for content length
Parallel validation for multiple streams

Quality Assurance

Validate across all bitrate variants
Test accessibility features
Verify closed caption compliance
Check audio-only variant functionality

Next Steps

Streaming Analysis

Learn about comprehensive streaming format analysis

Report Types

Understand all available analysis tools

Sample Library

Test validation with sample HLS streams

API Reference

Complete MediaStreamValidator API documentation

Need help with HLS validation or App Store submission? Contact our support team at support@probe.dev for personalized assistance with your streaming workflows.

Core Concepts

Streaming & Validation

Advanced Integration

​Overview

​Why HLS Validation Matters

App Store Requirements

Playback Quality

Specification Compliance

Debugging Support

​Getting Started

​Basic HLS Validation

​Quick Playlist-Only Check

​Comprehensive Validation

​Full Stream Analysis

​Parameter Configuration

​Apple HLS Compliance Requirements

​Essential Compliance Checks

​Common Validation Errors

​Critical Issues

​Warning-Level Issues

​Integration Workflows

​CI/CD Pipeline Integration

​GitHub Actions Example

​Jenkins Pipeline

​Pre-Publish Validation Script

​App Store Submission Workflow

​Pre-Submission Checklist

​Documentation for App Review

​Performance Optimization

​Validation Speed Tips

​Recommended Timeouts

​Troubleshooting

​Common Issues and Solutions

​Debugging with CLI Output

​Best Practices

Development Workflow

Production Deployment

Performance

Quality Assurance

​Next Steps

Streaming Analysis

Report Types

Sample Library

API Reference

Overview

Why HLS Validation Matters

Getting Started

Basic HLS Validation

Quick Playlist-Only Check

Comprehensive Validation

Full Stream Analysis

Parameter Configuration

Apple HLS Compliance Requirements

Essential Compliance Checks

Common Validation Errors

Critical Issues

Warning-Level Issues

Integration Workflows

CI/CD Pipeline Integration

GitHub Actions Example

Jenkins Pipeline

Pre-Publish Validation Script

App Store Submission Workflow

Pre-Submission Checklist

Documentation for App Review

Performance Optimization

Validation Speed Tips

Recommended Timeouts

Troubleshooting

Common Issues and Solutions

Debugging with CLI Output

Best Practices

Next Steps