Configuration and Settings

class default:
    """
    Module-wide default settings object.
    
    Attributes:
    - device (int or str or tuple): Default audio device(s)
    - samplerate (float): Default sample rate in Hz
    - blocksize (int): Default block size
    - channels (int or tuple): Default number of channels
    - dtype (str or numpy.dtype): Default data type for audio samples
    - latency (float or str): Default latency setting
    - extra_settings (object): Default platform-specific settings
    - clip_off (bool): Default clipping behavior
    - dither_off (bool): Default dithering behavior
    - never_drop_input (bool): Default input dropping behavior
    - prime_output_buffers_using_stream_callback (bool): Default buffer priming
    - hostapi (int): Default host API (read-only)
    """
    
    device = None
    samplerate = None
    blocksize = None
    channels = None
    dtype = None
    latency = None
    extra_settings = None
    clip_off = None
    dither_off = None
    never_drop_input = None
    prime_output_buffers_using_stream_callback = None
    
    @property
    def hostapi(self): ...
    
    def reset(self):
        """Reset all settings to their initial values."""

class AsioSettings:
    """
    ASIO-specific audio settings for Windows.
    
    Parameters:
    - channel_selectors (list of int): Specific ASIO channel selection (zero-based)
    
    Attributes:
    - channel_selectors (list): Selected ASIO channels
    """
    
    def __init__(self, channel_selectors): ...
    
    channel_selectors: list

class CoreAudioSettings:
    """
    Core Audio settings for macOS.
    
    Parameters:
    - channel_map (array_like, optional): Channel mapping for Core Audio
    - change_device_parameters (bool, optional): Allow device parameter changes
    - fail_if_conversion_required (bool, optional): Fail if conversion is required
    - conversion_quality (str, optional): Conversion quality ('min', 'low', 'medium', 'high', 'max')
    
    Attributes:
    - channel_map (array_like): Channel mapping configuration
    - change_device_parameters (bool): Device parameter change permission
    - fail_if_conversion_required (bool): Conversion requirement setting
    - conversion_quality (str): Conversion quality setting
    """
    
    def __init__(self, channel_map=None, change_device_parameters=False, fail_if_conversion_required=False, conversion_quality='max'): ...
    
    channel_map: object
    change_device_parameters: bool
    fail_if_conversion_required: bool
    conversion_quality: str

class WasapiSettings:
    """
    WASAPI settings for Windows.
    
    Parameters:
    - exclusive (bool, optional): Use exclusive mode
    - auto_convert (bool, optional): Enable automatic format conversion
    
    Attributes:
    - exclusive (bool): Exclusive mode setting
    - auto_convert (bool): Automatic conversion setting
    """
    
    def __init__(self, exclusive=False, auto_convert=False): ...
    
    exclusive: bool
    auto_convert: bool

import sounddevice as sd

# Configure default settings for all subsequent operations
sd.default.samplerate = 48000
sd.default.channels = 2
sd.default.dtype = 'float32'
sd.default.device = 'USB Audio Device'

# Now all operations will use these defaults
recording = sd.rec(duration=3.0)  # Uses 48000 Hz, 2 channels, float32
sd.play(recording)  # Uses the configured default device

# Check current default settings
print(f"Default sample rate: {sd.default.samplerate}")
print(f"Default channels: {sd.default.channels}")
print(f"Default device: {sd.default.device}")

import sounddevice as sd

# Set different devices for input and output
sd.default.device = ('Built-in Microphone', 'Built-in Output')

# Set different channel counts for input and output
sd.default.channels = (1, 2)  # 1 input channel, 2 output channels

# Simultaneous recording and playbook will use these settings
import numpy as np
test_signal = np.random.random((44100, 1))  # 1 second mono signal
recorded = sd.playrec(test_signal)  # Uses 1 input, 2 output channels

import sounddevice as sd

# Modify some defaults
sd.default.samplerate = 96000
sd.default.channels = 8

# Reset all defaults to initial values
sd.default.reset()

print(f"Sample rate after reset: {sd.default.samplerate}")  # None
print(f"Channels after reset: {sd.default.channels}")      # None

import sounddevice as sd

# Configure ASIO settings for professional audio interfaces
asio_settings = sd.AsioSettings(channel_selectors=(0, 1, 2, 3))

# Use ASIO settings with a stream
with sd.Stream(
    device='ASIO Device',
    channels=4,
    samplerate=96000,
    extra_settings=asio_settings
) as stream:
    print("Using ASIO with selected channels")
    # Audio processing with ASIO optimizations

import sounddevice as sd
import numpy as np

# Configure Core Audio settings
core_audio_settings = sd.CoreAudioSettings(
    channel_map=[0, 1, 4, 5],  # Use channels 0,1,4,5 from device
    change_device_parameters=True,
    priming_info=(512, 0)  # Prime with 512 frames
)

# Apply Core Audio settings
with sd.Stream(
    device='Built-in Output',
    channels=4,
    samplerate=44100,
    extra_settings=core_audio_settings
) as stream:
    print("Using Core Audio with custom channel mapping")
    # Use stream with optimized Core Audio settings

import sounddevice as sd

# Configure WASAPI for exclusive mode (lower latency)
wasapi_settings = sd.WasapiSettings(
    exclusive=True,              # Use exclusive mode
    auto_convert=False,          # No automatic format conversion
    system_sample_rate=False,    # Don't use system sample rate
    thread_priority='high'       # High thread priority
)

# Use WASAPI settings for low-latency audio
try:
    with sd.Stream(
        device='Speakers',
        samplerate=44100,
        channels=2,
        latency='low',
        extra_settings=wasapi_settings
    ) as stream:
        print("Using WASAPI exclusive mode")
        print(f"Actual latency: {stream.latency}")
        # Low-latency audio processing
        
except sd.PortAudioError as e:
    print(f"Exclusive mode failed: {e}")
    print("Falling back to shared mode")

import sounddevice as sd

def configure_for_recording():
    """Configure defaults optimized for high-quality recording."""
    sd.default.samplerate = 96000
    sd.default.channels = 2
    sd.default.dtype = 'float32'
    sd.default.latency = 'high'  # Higher latency for stable recording
    sd.default.never_drop_input = True

def configure_for_realtime():
    """Configure defaults optimized for real-time processing."""
    sd.default.samplerate = 44100
    sd.default.channels = 2
    sd.default.dtype = 'float32'
    sd.default.latency = 'low'   # Lower latency for real-time
    sd.default.never_drop_input = False

# Use different configurations for different scenarios
configure_for_recording()
long_recording = sd.rec(duration=300.0)  # 5-minute high-quality recording

configure_for_realtime()
# Real-time processing with low latency

import sounddevice as sd
import platform

def configure_for_platform():
    """Automatically configure settings based on the current platform."""
    system = platform.system()
    
    if system == 'Windows':
        # Check for ASIO devices
        devices = sd.query_devices()
        asio_devices = [d for d in devices if 'ASIO' in d['name']]
        
        if asio_devices:
            print("ASIO device found, using ASIO settings")
            sd.default.extra_settings = sd.AsioSettings()
        else:
            print("Using WASAPI settings")
            sd.default.extra_settings = sd.WasapiSettings(
                exclusive=False,
                auto_convert=True
            )
    
    elif system == 'Darwin':  # macOS
        print("Using Core Audio settings")
        sd.default.extra_settings = sd.CoreAudioSettings(
            change_device_parameters=True
        )
    
    else:  # Linux and others
        print("Using default settings for ALSA/JACK")
        sd.default.extra_settings = None
    
    # Set reasonable defaults for all platforms
    sd.default.samplerate = 44100
    sd.default.channels = 2
    sd.default.dtype = 'float32'

# Apply platform-specific configuration
configure_for_platform()

# Check what was configured
print(f"Platform: {platform.system()}")
print(f"Extra settings: {type(sd.default.extra_settings)}")