CtrlK
BlogDocsLog inGet started
Tessl Logo

thiennc-tesoglobal/ios-skills

Community-maintained Agent Skills for complete Swift and Apple-platform app delivery.

72

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Medium

Suggest reviewing before use

Overview
Quality
Evals
Security
Files

SKILL.mdskills/avfoundation-audio/

name:
avfoundation-audio
description:
Configure AVAudioSession categories, modes, route changes, interruptions, and build low-latency AVAudioEngine node graphs for recording, mixing, and audio processing in iOS and iPadOS apps.

AVFoundation Audio

Configure AVAudioSession and construct AVAudioEngine node graphs for playback, recording, real-time DSP, and multi-track audio pipelines in iOS and iPadOS.

Contents

  • Audio Session Configuration
  • Interruption & Route Change Handling
  • AVAudioEngine Architecture
  • Live Microphone Capture & Taps
  • Common Mistakes
  • Review Checklist
  • References

Audio Session Configuration

AVAudioSession coordinates app audio with the system audio subsystem. Defer activation until playback or recording begins to avoid prematurely silencing background audio.

import AVFAudio

@MainActor
final class AudioSessionManager {
    static let shared = AudioSessionManager()

    func configurePlayback() throws {
        let session = AVAudioSession.sharedInstance()
        try session.setCategory(.playback, mode: .moviePlayback, options: [])
        try session.setActive(true)
    }

    func configureRecording() throws {
        let session = AVAudioSession.sharedInstance()
        try session.setCategory(
            .playAndRecord,
            mode: .measurement,
            options: [.defaultToSpeaker, .allowBluetoothHFP]
        )
        try session.setActive(true)
    }

    func deactivate() throws {
        try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
    }
}

Key Categories and Modes

  • .playback: Media playback that continues when the Ring/Silent switch is set to silent or screen locks.
  • .record: Pure recording without playback; silences background audio.
  • .playAndRecord: Bidirectional audio (VoIP, chat, audio recording while monitoring). Use .defaultToSpeaker to prevent routing audio only to receiver.
  • .ambient: Mixes with other audio apps; silenced by Ring/Silent switch.

Interruption & Route Change Handling

Always observe AVAudioSession.interruptionNotification and AVAudioSession.routeChangeNotification asynchronously using NotificationCenter async sequences.

import AVFAudio

actor AudioNotificationObserver {
    private var task: Task<Void, Never>?

    func startObserving(
        onInterruption: @Sendable @escaping (Bool) -> Void,
        onPauseForRouteLoss: @Sendable @escaping () -> Void
    ) {
        task = Task {
            for await notification in NotificationCenter.default.notifications(named: AVAudioSession.interruptionNotification) {
                guard let userInfo = notification.userInfo,
                      let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
                      let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { continue }

                switch type {
                case .began:
                    onInterruption(true)
                case .ended:
                    let optionsValue = userInfo[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
                    let shouldResume = AVAudioSession.InterruptionOptions(rawValue: optionsValue).contains(.shouldResume)
                    onInterruption(!shouldResume)
                @unknown default:
                    break
                }
            }
        }
    }

    func stopObserving() {
        task?.cancel()
        task = nil
    }
}

Pause playback immediately when AVAudioSessionRouteChangeReasonKey indicates .oldDeviceUnavailable (e.g., headphones disconnected).

AVAudioEngine Architecture

AVAudioEngine coordinates a graph of AVAudioNode instances (player nodes, mixer nodes, effect nodes) connected together.

import AVFAudio

@MainActor
final class AudioEngineController {
    private let engine = AVAudioEngine()
    private let playerNode = AVAudioPlayerNode()

    func setupGraph(audioFileURL: URL) throws {
        let file = try AVAudioFile(forReading: audioFileURL)
        let format = file.processingFormat

        engine.attach(playerNode)
        engine.connect(playerNode, to: engine.mainMixerNode, format: format)

        try engine.start()

        playerNode.scheduleFile(file, at: nil) {
            // Playback completed
        }
        playerNode.play()
    }

    func stop() {
        playerNode.stop()
        engine.stop()
        engine.reset()
    }
}

Live Microphone Capture & Taps

To analyze or stream microphone PCM buffers, install an audio tap on the inputNode. Always remove previous taps before installing a new tap or tearing down.

import AVFAudio

final class MicrophoneTapManager: Sendable {
    private let engine = AVAudioEngine()

    func startTapping(bufferHandler: @escaping @Sendable (AVAudioPCMBuffer, AVAudioTime) -> Void) throws {
        let inputNode = engine.inputNode
        let format = inputNode.outputFormat(forBus: 0)

        inputNode.removeTap(onBus: 0)
        inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { buffer, time in
            bufferHandler(buffer, time)
        }

        engine.prepare()
        try engine.start()
    }

    func stopTapping() {
        engine.inputNode.removeTap(onBus: 0)
        engine.stop()
    }
}

Common Mistakes

  • Activating session at app launch: Causes unwanted background audio suspension. Deactivate or defer activation until the user requests audio.
  • Mismatching audio formats in engine connections: Connecting nodes with incompatible sample rates or channel counts without a mixer or format converter throws an exception.
  • Duplicate tap installation: Calling installTap(onBus:bufferSize:format:) on a bus that already has a tap installed crashes at runtime. Always call removeTap(onBus:) first.
  • Ignoring route loss: Failing to pause playback when headphones disconnect blares audio through built-in speakers.
  • Retaining AVAudioEngine across session resets: Handle AVAudioEngineConfigurationChange by rebuilding graph or restarting the engine.

Review Checklist

  • Does AVAudioSession configuration set appropriate category, mode, and options (.defaultToSpeaker, .allowBluetoothHFP)?
  • Is setActive(true) deferred until audio playback/recording actually starts?
  • Is setActive(false, options: .notifyOthersOnDeactivation) invoked when stopping to restore other audio apps?
  • Are route changes observed, specifically pausing on .oldDeviceUnavailable?
  • Are interruptions (.began and .ended with .shouldResume) handled gracefully?
  • Does microphone capture check and request AVAudioApplication.requestRecordPermission() prior to starting?
  • Are audio node taps properly removed prior to re-installing or stopping?

References

  • Audio Engine Patterns — Advanced mixer graphs, EQ, audio conversion, and unit tests.
  • AVFAudio Documentation — Official Apple AVFAudio API reference.
  • AVAudioSession Guide — Audio session lifecycle, routing, and categories.
  • AVAudioEngine Guide — Real-time audio node processing graph.

skills

avfoundation-audio

SKILL.md

.mcp.json

README.md

tile.json