target audience

To build a truly seamless, gapless looping audio player in Swift, you should use AVQueuePlayer paired with AVPlayerLooper.

While a basic AVAudioPlayer with numberOfLoops = -1 works well for simple, uncompressed local files, it can suffer from noticeable gaps or stuttering with compressed formats like MP3 or when streaming over a network. Using Apple’s dedicated AVPlayerLooper solves this by pre-priming a queue of player items to eliminate latency between the end and restarting of the audio track. Implementation Guide

You can implement seamless looping by importing the AVFoundation framework and instantiating an AVPlayerLooper alongside an AVQueuePlayer.

import Foundation import AVFoundation class SeamlessAudioPlayer { // Keep strong references to both the player and looper private var queuePlayer = AVQueuePlayer() private var playerLooper: AVPlayerLooper? func playLoopingAudio(from url: URL) { // 1. Create a player item from the asset URL let playerItem = AVPlayerItem(url: url) // 2. Initialize the looper with your queue player and template item // This manages the underlying queue ‘treadmill’ automatically playerLooper = AVPlayerLooper(player: queuePlayer, templateItem: playerItem) // 3. Start playback queuePlayer.play() } func stop() { queuePlayer.pause() queuePlayer.removeAllItems() playerLooper = nil } } Use code with caution. Architecture & Mechanics

Understanding the underlying mechanics explains why this approach works while others cause lagging:

The “Treadmill Pattern”: AVPlayerLooper optimizes the queue by automatically copying and pre-buffering multiple instances of the same AVPlayerItem. As one instance finishes playing, the next one is already fully primed and ready to take over instantly.

Asset Lifecycle Management: You must retain a strong instance reference to playerLooper (e.g., as a class-level variable). Deallocating it prematurely will halt the looping routine and cause your audio to stop after a single iteration. Crucial Technical Requirements

Even with the correct codebase, structural quirks in your media files can ruin seamless execution:

ios – AVPlayerLoop not seamlessly looping – Swift 4 – Stack Overflow