Skip to content

Adam Greenwell

Cloud Storage Guide

Offload Listenup audio files to cloud storage providers to reduce server bandwidth and improve delivery performance.

Overview

Cloud storage is completely optional and disabled by default. ListenUp works perfectly with local storage for most sites.

Consider cloud storage if you:

  • Have high traffic volume
  • Want to reduce server bandwidth usage
  • Need geographic distribution (CDN)
  • Want to separate media delivery from your web server

Supported providers:

  • Amazon S3
  • Cloudflare R2
  • Google Cloud Storage

Benefits

Reduced Bandwidth

Audio files are served directly from cloud infrastructure, not your web server. This reduces:

  • Server load
  • Bandwidth costs (if your host charges for bandwidth)
  • Risk of server overload during traffic spikes

Improved Performance

Cloud providers have global infrastructure:

  • Files served from edge locations closer to users
  • High-capacity networks designed for media delivery
  • Better performance for international audiences

Signed URL Security

All cloud URLs are signed with expiration times:

  • URLs are time-limited (prevents permanent sharing)
  • Fresh URLs generated for each request
  • Prevents unauthorized access and hotlinking

AWS S3 Configuration

Step 1: Create an S3 Bucket

  1. Log into AWS Console
  2. Go to S3 service
  3. Click Create bucket
  4. Enter a unique bucket name (e.g., mysite-listenup-audio)
  5. Select your preferred region
  6. Keep “Block all public access” enabled (signed URLs don’t require public access)
  7. Click Create bucket

Step 2: Create IAM Credentials

  1. Go to IAM service
  2. Click Users → Create user
  3. Enter a username (e.g., listenup-s3-user)
  4. Click Next
  5. Select Attach policies directly
  6. Click Create policy and use this JSON:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}
  1. Name the policy (e.g., ListenUpS3Policy)
  2. Attach the policy to your user
  3. Create the user
  4. Go to Security credentials tab
  5. Create an Access key (select “Application running outside AWS”)
  6. Save the Access Key ID and Secret Access Key

Step 3: Configure in ListenUp

  1. Go to Settings → ListenUp → Cloud Storage
  2. Select Amazon S3 as provider
  3. Enter your credentials:
  • Access Key ID
  • Secret Access Key
  • Bucket Name
  • Region (e.g., us-east-1)
  1. Click Test Connection to verify
  2. Enable cloud storage
  3. Save settings

Optional: Custom Endpoint

For S3-compatible services (DigitalOcean Spaces, Linode Object Storage, etc.):

  1. Enter the service endpoint URL
  2. Configure region as required by the service

Cloudflare R2 Configuration

Cloudflare R2 offers S3-compatible storage with no egress fees.

Step 1: Create an R2 Bucket

  1. Log into Cloudflare Dashboard
  2. Go to R2 in the sidebar
  3. Click Create bucket
  4. Enter a bucket name
  5. Select location (optional)
  6. Click Create bucket

Step 2: Create API Credentials

  1. In R2 settings, go to Manage R2 API Tokens
  2. Click Create API token
  3. Configure permissions:
  • Object Read & Write – Required
  • Specify bucket or allow all buckets
  1. Click Create API Token
  2. Save the credentials:
  • Access Key ID
  • Secret Access Key

Step 3: Get Account ID and Endpoint

  1. Your Account ID is in the dashboard URL or R2 overview
  2. The endpoint format is: https://<account-id>.r2.cloudflarestorage.com

Step 4: Configure in ListenUp

  1. Go to Settings → ListenUp → Cloud Storage
  2. Select Cloudflare R2 as provider
  3. Enter your credentials:
  • Access Key ID
  • Secret Access Key
  • Bucket Name
  • Account ID
  1. Click Test Connection to verify
  2. Enable cloud storage
  3. Save settings

R2 Benefits

  • No egress fees – Pay only for storage, not downloads
  • S3-compatible – Works with existing S3 tools
  • Global network – Cloudflare’s edge network

Google Cloud Storage Configuration

Step 1: Create a GCS Bucket

  1. Log into Google Cloud Console
  2. Go to Cloud Storage → Buckets
  3. Click Create
  4. Enter a unique bucket name
  5. Select location type and region
  6. Choose Standard storage class for frequently accessed files
  7. Keep default access control (Uniform)
  8. Click Create

Step 2: Create Service Account

  1. Go to IAM & Admin → Service Accounts
  2. Click Create Service Account
  3. Enter a name (e.g., listenup-storage)
  4. Click Create and Continue
  5. Grant the Storage Object Admin role
  6. Click Continue → Done

Step 3: Create Service Account Key

  1. Click on the service account you created
  2. Go to Keys tab
  3. Click Add Key → Create new key
  4. Select JSON format
  5. Click Create
  6. Save the downloaded JSON file securely

Step 4: Configure in ListenUp

  1. Go to Settings → ListenUp → Cloud Storage
  2. Select Google Cloud Storage as provider
  3. Enter your credentials:
  • Bucket Name
  • Service Account JSON – Paste the entire contents of the JSON key file
  1. Click Test Connection to verify
  2. Enable cloud storage
  3. Save settings

GCS Benefits

  • Integrated with Google Cloud – If you already use GCP
  • Multi-regional options – Global redundancy available
  • Fine-grained IAM – Detailed access control

Migrating Existing Audio

When you enable cloud storage, new audio files are automatically uploaded. Existing local files need to be migrated.

Using WP-CLI (Recommended)

# Upload all local files to cloud
wp listenup cloud-upload --all

# Upload specific post
wp listenup cloud-upload --post-id=123

# Re-upload existing cloud files
wp listenup cloud-upload --all --force

# Dry run to see what would be uploaded
wp listenup cloud-upload --all --dry-run

From Admin Interface

  1. Go to Settings → ListenUp → Audio Library
  2. Filter by Storage: Local
  3. Use bulk actions to upload selected posts

Managing Cloud Files

Deleting Audio

When you delete audio from a post:

  • Local file is deleted from server
  • Cloud file is also deleted (if enabled in settings)

Regenerating Audio

When you regenerate audio:

  1. Old local file is replaced
  2. New file is uploaded to cloud
  3. Old cloud file is deleted

Checking Storage Status

View storage location for all posts:

  1. Go to Settings → ListenUp → Audio Library
  2. Storage column shows: Local, Cloud, or both

CORS Configuration

If you experience CORS errors, configure your bucket:

S3 CORS

In bucket settings → Permissions → CORS:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://yoursite.com"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3600
  }
]

R2 CORS

In bucket settings → Settings → CORS Policy:

[
  {
    "AllowedOrigins": ["https://yoursite.com"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3600
  }
]

GCS CORS

Using gsutil:

gsutil cors set cors.json gs://your-bucket-name

Where cors.json contains:

[
  {
    "origin": ["https://yoursite.com"],
    "method": ["GET", "HEAD"],
    "responseHeader": ["Content-Type"],
    "maxAgeSeconds": 3600
  }
]

Signed URL Expiration

Cloud storage URLs include expiration times for security.

How It Works

  1. Player initializes on page load
  2. AJAX request fetches fresh signed URL
  3. URL is valid for limited time (typically 1 hour)
  4. New URL generated if needed for downloads

Page Caching Compatibility

ListenUp fetches URLs via AJAX, so:

  • Works with all page caching plugins
  • Works with CDN caching (Cloudflare, Varnish)
  • URLs are always fresh regardless of page cache age

This was improved in version 1.5.13 to prevent expired URL issues.

Cost Considerations

AWS S3 Pricing

  • Storage: ~$0.023/GB/month (varies by region)
  • Requests: ~$0.005 per 1,000 GET requests
  • Data transfer: ~$0.09/GB (first 10TB/month)

Cloudflare R2 Pricing

  • Storage: $0.015/GB/month
  • Requests: $0.36 per million Class A operations
  • Data transfer: Free (no egress fees)

Google Cloud Storage

  • Storage: ~$0.020/GB/month (Standard class)
  • Requests: $0.05 per 10,000 Class B operations
  • Data transfer: ~$0.12/GB (varies by region)

Tip: Cloudflare R2 is often most cost-effective due to free egress.

Troubleshooting

Connection Test Fails

  1. Verify credentials are correct
  2. Check bucket name and region
  3. Verify IAM permissions
  4. Check network connectivity from server

Upload Fails

  1. Check bucket write permissions
  2. Verify bucket exists
  3. Check for storage quota limits
  4. Review debug.log for detailed errors

Audio Not Playing from Cloud

  1. Check CORS configuration
  2. Verify signed URL is being generated
  3. Check browser console for errors
  4. Try clearing page cache

See full Troubleshooting Guide →

Security Best Practices

  1. Use dedicated credentials – Don’t use root/admin credentials
  2. Minimum permissions – Only grant required permissions
  3. Rotate credentials – Periodically rotate access keys
  4. Enable bucket logging – Monitor access patterns
  5. Keep bucket private – Don’t enable public access; signed URLs handle access

Back to Documentation Index →