Skip to content

Adam Greenwell

Troubleshooting Guide

Common issues and solutions for ListenUp.

Audio Not Playing

Symptoms: Player appears but audio doesn't play, error messages in browser console.

Check Audio Generation Status

  1. Edit the post in WordPress
  2. Find the ListenUp meta box
  3. Check the status:
    • No audio – Generate audio first
    • Generating… – Wait for completion
    • Ready – Audio should be playable
    • Error – See error message for details

Check Browser Console

  1. Open browser developer tools (F12)
  2. Go to Console tab
  3. Look for error messages containing "ListenUp" or "MEDIA_ELEMENT_ERROR"

Common Console Errors

MEDIA_ELEMENT_ERROR: Format error

  • Audio file may be corrupted
  • Try regenerating the audio

403 Forbidden on audio URL

  • Signed URL may have expired (cloud storage)
  • Clear page cache and refresh
  • Check cloud storage credentials

404 Not Found

  • Audio file may have been deleted
  • Regenerate the audio

Verify Audio File Exists

For local storage:

  1. Connect via FTP/SFTP
  2. Navigate to wp-content/uploads/listenup-audio/
  3. Look for files matching the post ID

For cloud storage:

  1. Log into your cloud provider console
  2. Check your bucket for the audio files

Check Plugin Conflicts

  1. Deactivate other plugins one by one
  2. Test audio playback after each deactivation
  3. Identify the conflicting plugin

Generation Errors

Symptoms: "Generate Audio" fails with an error message.

Invalid or Expired API Key

Error: "API request failed" or "401 Unauthorized"

Solution:

  1. Go to Settings → ListenUp
  2. Verify your Murf.ai API key is correct
  3. Check your Murf.ai account is active
  4. Generate a new API key if needed

API Rate Limiting

Error: "429 Too Many Requests"

Solution:

  • Wait a few minutes before trying again
  • Check your Murf.ai plan limits
  • Consider upgrading your Murf.ai plan

Content Too Long

Error: Content should auto-chunk, but if it fails:

Solution:

  1. Check for unusual content (very long words, special characters)
  2. Try removing problematic content
  3. Enable debug logging to identify the issue

Network Timeout

Error: "Request timeout" or connection errors

Solution:

  1. Check your server's internet connectivity
  2. Verify Murf.ai service is operational
  3. Try again later if Murf.ai is experiencing issues
  4. Increase PHP timeout if consistently timing out

Server Memory Issues

Error: PHP memory errors during generation

Solution:

  1. Increase PHP memory limit in wp-config.php: 
    define('WP_MEMORY_LIMIT', '256M');
  2. Contact your hosting provider if unable to increase

Gen2 Control Issues

Symptoms: Audio generates, but one of the Gen2 settings does not behave the way you expected.

Direct Base64 Response Mode Fails

Cause: The encoded audio is returned in the API response before ListenUp writes it to the local cache. Very large responses can run into server memory, timeout, or upload-directory write limits.

Solution:

  1. Switch Audio Response Mode back to URL and try generating again
  2. Confirm wp-content/uploads/listenup-audio/ is writable
  3. Check PHP memory and timeout settings if large posts fail
  4. Enable debug logging and look for Murf or ListenUp API errors

URL mode and direct base64 mode both cache audio locally after generation, so URL mode is the safer fallback on tighter hosting.

Target Audio Duration Not Exact

Cause: Murf.ai treats target duration as a generation target, not a frame-perfect audio editor. ListenUp also skips target duration for long content that has to be split into chunks.

Solution:

  1. Use target duration on shorter posts that generate as a single file
  2. Keep the target realistic for the amount of text being spoken
  3. Adjust the source text or speaking speed if the result is too far off
  4. Regenerate audio after changing duration, text, speed, or pitch

Pause Tags Not Working

Cause: Pause tags need a supported numeric value.

Solution:

  1. Use the format [pause 1s]
  2. Keep pauses between 0.1s and 5s
  3. Regenerate audio after adding or changing pause tags
  4. Check that another plugin did not rewrite the brackets or strip the tag from the saved content

Word Timings Are Not Visible

Cause: Word timing metadata is stored with generated audio for future transcript and highlighting features. ListenUp does not display a frontend transcript yet.

Solution:

  1. Enable Word Timing Metadata before generating audio
  2. Regenerate older cached audio if you need timing metadata added
  3. Confirm the audio generation completed successfully

Cloud Storage Issues

Symptoms: Audio not uploading to cloud, signed URL errors.

Expired Signed URLs

Symptoms: Audio plays briefly then stops, or shows 403 error after page was cached.

Cause: Page caching stored a signed URL that expired.

Solution: This was fixed in version 1.5.136. Update to the latest version. URLs are now fetched fresh via AJAX when the player initializes.

Only the Last Part of a Long Post Plays from Cloud Storage

Symptoms: A long, chunked article plays from cloud storage but the visitor only hears the final section instead of the complete recording. The same post plays in full when served from local storage.

Cause: In releases before 1.5.137, the cloud copy for a chunked post could be published from the last chunk rather than the concatenated complete article audio.

Solution:

  1. Update to version 1.5.137 or newer
  2. No manual cleanup is required — ListenUp detects the affected posts and republishes the complete recording automatically
  3. If a specific post still plays short, regenerate its audio from the post editor and confirm the Audio Library shows a cloud copy

Chunked Posts Re-upload on Every Bulk Run

Symptoms: Upload All Local Only keeps re-uploading the same chunked posts each time it runs, and the backlog never reaches zero.

Cause: Before 1.5.137, bulk upload did not recognize chunked posts that were already in cloud storage, so it queued them again on every pass.

Solution: Update to version 1.5.137 or newer, then reopen Settings → ListenUp → Audio Library so the admin cache refreshes before starting another run.

Posts with Pre-roll Audio Will Not Upload to Cloud

Symptoms: Posts that use pre-roll audio stay local-only and fail during bulk or single cloud upload.

Cause: A pre-roll resolution bug prevented these posts from completing cloud upload before 1.5.137.

Solution: Update to version 1.5.137 or newer and retry the upload. The pre-roll is excluded from the post's complete article audio, so the uploaded file contains only the article recording.

Cloud Playback Never Used on Non-MP3 Sites

Symptoms: Cloud storage is configured and files upload successfully, but the frontend player always requests local audio.

Cause: Before 1.5.137, cloud playback assumed MP3 output, so sites generating WAV, OGG, or another format never used their cloud copies.

Solution: Update to version 1.5.137 or newer. If concatenated non-WAV files accumulated in wp-content/uploads/listenup-audio/ under an older build, they are no longer regenerated on each playback and can be cleared once the affected posts play correctly.

Bulk Cloud Upload Counts Look Wrong

Symptoms: The Audio Library bulk upload panel shows different totals for processed posts and uploaded files, or rows still look local-only after a partial test migration.

Cause: Bulk migration progress is tracked by post. A post can have multiple physical audio files on disk, especially when long-form content was chunked, but the Audio Library only treats the canonical playable audio file as the cloud migration target.

Solution:

  1. Update to version 1.5.137 or newer
  2. Reopen Settings → ListenUp → Audio Library so the admin cache refreshes
  3. Use Upload All Local Only to retry posts that still need a canonical cloud copy
  4. If you previously tested an older bulk upload build, rebuild the Audio Library cache with wp listenup audio-library-cache rebuild

Internal chunk files are skipped during admin bulk migration so they do not overwrite the cloud metadata used for frontend signed playback.

Invalid Credentials

Error: "Access Denied" or authentication errors

Solution:

  1. Go to Settings → ListenUp → Cloud Storage
  2. Verify all credentials are correct
  3. Re-enter credentials if needed
  4. Check IAM permissions for your access key

Bucket Configuration

Error: "Bucket not found" or "NoSuchBucket"

Solution:

  1. Verify bucket name is correct (case-sensitive)
  2. Check bucket exists in your cloud console
  3. Verify bucket region matches configuration

Permission Issues

Error: "Access Denied" when uploading

Required S3 Permissions:

{
  "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/*"
      ]
    }
  ]
}

CORS Configuration

Error: CORS errors in browser console

Solution: Configure CORS on your bucket. For S3:

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

Learn more about Cloud Storage →

Player Not Appearing

Symptoms: No audio player visible on posts with audio.

Check Auto Placement Settings

  1. Go to Settings → ListenUp
  2. Check Auto Placement setting
  3. Ensure it includes your post type (Posts, Pages, or Both)
  4. Check Placement Position (Before/After Content)

Verify Audio Exists

  1. Edit the post
  2. Check ListenUp meta box shows "Ready" status
  3. If no audio, generate it first

Check for Theme Conflicts

Some themes may hide or conflict with the player:

  1. Switch to a default theme (Twenty Twenty-Four)
  2. Test if player appears
  3. If working, issue is theme-related

Check Player Display Settings

If the player appears but the controls are not what you expect:

  1. Go to Settings → ListenUp → Display
  2. Confirm the player layout is set to Featured player or Compact controls
  3. Check whether skip controls or the playback speed selector are hidden
  4. Confirm the default playback speed is set to the expected value

Check Shortcode Syntax

If using manual placement:

Correct: [listenup]

Common mistakes:

  • Wrong brackets: (listenup)
  • Extra spaces: [ listenup ]
  • Wrong case: [ListenUp]

JavaScript Errors

  1. Open browser console (F12)
  2. Look for JavaScript errors
  3. May indicate script conflicts with other plugins/themes

Check for Page Builders

Some page builders may strip shortcodes. Try:

  1. Using a Custom HTML block
  2. Adding shortcode in theme template
  3. Using automatic placement instead

Download Issues

Symptoms: Download button missing or downloads fail.

Download Button Not Visible

Cause: Download restrictions are enabled

Solution:

  1. Go to Settings → ListenUp
  2. Check Download Restriction setting
  3. Set to "Allow All" if you want everyone to download
  4. Set to "Logged In Only" for authenticated users

Download Fails or Corrupted File

Cause: File concatenation issue (for chunked content)

Solution:

  1. Check audio format supports chunking (MP3, OGG work best)
  2. Try regenerating the audio
  3. Check server has enough memory for concatenation

Large File Download Timeout

Cause: Long content with many chunks takes time to concatenate

Solution:

  1. Increase PHP max_execution_time
  2. Use cloud storage (serves pre-concatenated files)
  3. Consider shorter content

Pronunciation Issues

Symptoms: Words pronounced incorrectly despite dictionary rules.

Rules Not Applied

  1. Verify pronunciation dictionary is enabled
  2. Check rules are saved correctly
  3. Regenerate audio – rules only apply to new generations

Check Rule Format

SAY_AS type:

  • Word: AWS
  • Pronunciation: Amazon Web Services
  • Type: SAY_AS

IPA type:

  • Word: live
  • Pronunciation: laɪv
  • Type: IPA

Case Sensitivity

Pronunciation rules are case-sensitive. "AWS" won't match "aws" in content.

Word Boundaries

Rules match whole words. "API" won't change "APIs" unless you add both.

Learn more about Pronunciation →

Pre-roll Issues

Symptoms: Pre-roll audio not playing or not generating.

Pre-roll Not Playing

  1. Check pre-roll is configured in Settings → ListenUp → Pre-roll
  2. Verify pre-roll file exists (if uploaded)
  3. Regenerate audio with pre-roll enabled

Pre-roll Generation Failed

Cause: Same issues as regular audio generation

Solution:

  1. Check API key is valid
  2. Verify pre-roll text isn't too long
  3. Try generating with different text

Pre-roll File Missing

If you uploaded a file that's now missing:

  1. Re-upload the pre-roll audio
  2. Save settings
  3. Regenerate audio for affected posts

Performance Issues

Symptoms: Slow audio generation, site slowdown.

Slow Generation

Causes:

  • Long content (many chunks)
  • Slow Murf.ai API response
  • Server network issues

Solutions:

  • Consider shorter content or summaries
  • Generate during off-peak hours
  • Use WP-CLI for bulk generation in background

Site Slowdown

Cause: Large audio files or many AJAX requests

Solutions:

  1. Enable cloud storage to offload files
  2. Optimize audio format (MP3 is most efficient)
  3. Limit audio library shortcode results

Memory Issues During Bulk Operations

Solution:

# Use batch size flag with WP-CLI
wp listenup generate --all --batch-size=5

WP-CLI Issues

Symptoms: Commands fail or produce errors.

Command Not Found

Error: 'listenup' is not a recognized command

Solution:

  1. Verify plugin is activated
  2. Run wp plugin list to confirm
  3. Clear WP-CLI cache: wp cli cache clear

Permission Errors

Error: Cannot write to uploads directory

Solution:

  1. Check directory permissions
  2. Run as correct user: sudo -u www-data wp listenup generate --all

Timeout on Large Sites

Error: Command times out during bulk operations

Solution:

  1. Use smaller batch sizes
  2. Run in background with screen/tmux
  3. Process by post type or date range

Debug Mode

Enable debugging to get more detailed error information:

  1. Add to wp-config.php:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

  1. Check /wp-content/debug.log for ListenUp errors

  2. Look for entries containing "ListenUp" or "listenup"

Still Having Issues?

If you've tried these solutions and still have problems:

  1. Check the WordPress.org forums – Search for similar issues
  2. Post a support request – Include:
    • WordPress version
    • PHP version
    • Plugin version
    • Error messages (from browser console and debug.log)
    • Steps to reproduce

WordPress.org Support Forums →

Back to Documentation Index →