### Setup virtual environment for library usage

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Install the package into a local virtual environment for use as a Python library.

```bash
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install muselsl
```

--------------------------------

### start()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Starts streaming and data collection from the device.

```APIDOC
## start() -> None

### Description
Start streaming and data collection from device. Initializes sample buffers and timestamp correction parameters.
```

--------------------------------

### Install muselsl

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Installation commands for the muselsl package.

```bash
# Via pipx (recommended)
pipx install muselsl

# Via pip (in virtual environment)
pip install muselsl
```

--------------------------------

### muselsl record_direct output example

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Example output showing direct recording from a specific device address.

```bash
$ muselsl record_direct --duration 30 --address 00:1A:7D:DA:71:13
Connecting to Muse : 00:1A:7D:DA:71:13...
Start recording at time t=0.000
Connected. Continuing with data collection...
Interrupt received. Exiting data collection.
Done - wrote file: recording_2024-01-15-14.31.00.csv.
```

--------------------------------

### muselsl record_direct examples

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Common usage patterns for direct recording without LSL.

```bash
muselsl record_direct --duration 120
```

```bash
muselsl record_direct --address 00:1A:7D:DA:71:13 --filename ./eeg_data.csv
```

--------------------------------

### Install muselsl via pipx on Linux

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Use pipx to install the command-line tool on Debian/Ubuntu systems.

```bash
sudo apt install pipx
pipx ensurepath        # one-time: adds pipx's app folder to your PATH
# close and reopen your terminal once after running ensurepath
pipx install muselsl
```

--------------------------------

### List available Muse devices

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Verify the installation and list connected Muse devices.

```bash
muselsl list
```

--------------------------------

### Start streaming

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Begins data transmission from the device.

```python
def start(self) -> None
```

--------------------------------

### Install muselsl via pipx on Windows

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Use pipx to install the command-line tool on Windows via PowerShell.

```powershell
py -m pip install --user pipx
py -m pipx ensurepath
# close and reopen your terminal once after running ensurepath
pipx install muselsl
```

--------------------------------

### muselsl record output example

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Example output showing the recording process for an EEG stream.

```bash
$ muselsl record --duration 60 --type EEG
Looking for a EEG stream...
Started acquiring data.
Looking for a Markers stream...
Can't find Markers stream.
Start recording at time t=0.000
Time correction: 0.0
...
Done - wrote file: EEG_recording_2024-01-15-14.30.45.csv
```

--------------------------------

### muselsl record examples

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Common usage patterns for recording data via LSL.

```bash
muselsl record --duration 60
```

```bash
muselsl record --duration 120 --type PPG --filename ./data/ppg_session.csv
```

```bash
muselsl record --type ACC --dejitter
```

--------------------------------

### Install muselsl via pipx on macOS

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Use pipx to install the command-line tool in an isolated environment.

```bash
brew install pipx
pipx ensurepath        # one-time: adds pipx's app folder to your PATH
# close and reopen your terminal once after running ensurepath
pipx install muselsl
```

--------------------------------

### Initialize Athena and Handle Optics Data

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Example of connecting to an Athena device and buffering optics data for processing.

```python
from muselsl.athena import Athena
import numpy as np

optics_buffer = []

def handle_optics(data, timestamps):
    optics_buffer.append((data.copy(), timestamps.copy()))
    if len(optics_buffer) >= 64:  # 1 second at 64 Hz
        combined = np.concatenate([o[0] for o in optics_buffer], axis=1)
        print(f"1 second of optics: {combined.shape}")
        optics_buffer.clear()

athena = Athena(
    '00:1A:7D:DA:71:13',
    callback_optics=handle_optics,
)

athena.connect()
athena.start()
```

--------------------------------

### Initialize StreamDescriptor instances

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/types.md

Examples of initializing StreamDescriptor for different sensor types.

```python
StreamDescriptor(
    name='EEG',
    stype='EEG',
    n_channels=5,
    channel_names=('TP9', 'AF7', 'AF8', 'TP10', 'Right AUX'),
    rate=256.0,
    chunk=12,
    unit='microvolts'
)
```

```python
StreamDescriptor(
    name='OPTICS',
    stype='optics',
    n_channels=16,
    channel_names=('OPT0', 'OPT1', ..., 'OPT15'),
    rate=64.0,
    chunk=3,
    unit='unitless'
)
```

```python
StreamDescriptor(
    name='ACC',
    stype='accelerometer',
    n_channels=3,
    channel_names=('X', 'Y', 'Z'),
    rate=52.0,
    chunk=1,
    unit='g'
)
```

--------------------------------

### Configure Muse S with Optics

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Example of streaming with specific Muse S model settings and optics enabled.

```python
from muselsl import stream

stream(
    address='00:1A:7D:DA:71:13',
    model='athena',
    optics_enabled=True,
    disable_light=True,
    preset='p1041'
)
```

--------------------------------

### Start LSL stream

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Initializes an LSL stream from a Muse device with optional sensor and connection settings.

```bash
muselsl stream [options]
```

```bash
$ muselsl stream --address 00:1A:7D:DA:71:13
Connecting to Muse: 00:1A:7D:DA:71:13...
[0.2s] Connecting to 00:1A:7D:DA:71:13...
[0.5s] BLE connected.
[muse] Subscribing to EEG sensors...
[muse] Subscribing to control channel...
[muse] Headband setup complete.
Connected.
Streaming EEG...
stream alive: 0.12s since last data (disconnect at 3s)
stream alive: 1.15s since last data (disconnect at 3s)
...
Disconnected.
```

```bash
muselsl stream
```

```bash
muselsl stream --address 00:1A:7D:DA:71:13 --ppg --acc
```

```bash
muselsl stream --model athena --optics --disable-light
```

```bash
muselsl stream --lsltime
```

```bash
muselsl stream --retries 5 -l debug
```

--------------------------------

### Start Muse Stream

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Command to initiate the Muse LSL stream in a terminal.

```bash
muselsl stream
```

--------------------------------

### Find Muse devices

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_stream.md

Examples showing how to locate the first available Muse device or a specific device by name.

```python
from muselsl import find_muse

muse = find_muse()
if muse:
    print(f"Connecting to {muse['name']}")
```

```python
from muselsl import find_muse

muse = find_muse(name='Muse-41D2')
```

--------------------------------

### Install or Upgrade pylsl

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Commands to ensure the required LSL library is installed or updated to a compatible version.

```bash
pip install --upgrade pylsl
```

```bash
pip install pylsl==1.10.5
```

--------------------------------

### Scan Method Signature and Output

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/backends.md

Method signature for scanning devices and an example of the returned device list.

```python
def scan(self, timeout: float = 10) -> list[dict]
```

```python
[
    {'name': 'Muse-41D2', 'address': '00:1A:7D:DA:71:13'},
    {'name': 'Muse-1234', 'address': '00:1A:7D:DA:71:14'},
]
```

--------------------------------

### stream(address, optics_enabled=False, model='muse2')

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/module_index.md

Starts an LSL stream for the specified Muse device.

```APIDOC
## Function: stream

### Description
Starts an LSL stream for the specified Muse device address.

### Parameters
- **address** (str) - Required - The MAC address of the Muse device.
- **optics_enabled** (bool) - Optional - Whether to enable optics (e.g., for Athena/Muse S Gen 3).
- **model** (str) - Optional - The device model (e.g., 'muse2', 'athena').
```

--------------------------------

### CSV Output Format Examples

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Examples of the expected CSV output structure for EEG data and EEG data with markers.

```text
timestamps,TP9,AF7,AF8,TP10,Right AUX
0.000,-12.345,-5.678,3.456,2.109,-1.234
0.004,-12.456,-5.789,3.567,2.210,-1.345
...
```

```text
timestamps,TP9,AF7,AF8,TP10,Right AUX,Marker0,Marker1
0.000,-12.345,-5.678,3.456,2.109,-1.234,0,0
5.234,-10.123,-3.456,5.789,4.567,-0.123,1,0
...
```

--------------------------------

### View EEG with default settings

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_view.md

Launches the viewer using default parameters after starting the LSL stream.

```python
# Terminal 1: Start stream
# muselsl stream

# Terminal 2: View stream
from muselsl import view

view()
```

--------------------------------

### Start and Stop Streaming

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Methods to initiate or halt data collection from the device.

```python
def start(self) -> None
```

```python
muse = Muse('00:1A:7D:DA:71:13', callback_eeg=handle_eeg)
muse.connect()
muse.start()
```

```python
def stop(self) -> None
```

--------------------------------

### Stream Muse data

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Start streaming data from a Muse device using CLI or Python.

```bash
muselsl stream

muselsl stream --address 00:1A:7D:DA:71:13 --ppg --acc --gyro
```

```python
from muselsl import stream, list_muses
muses = list_muses()
stream(muses[0]['address'])
```

--------------------------------

### Real-Time EEG Acquisition

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Example of connecting to a device and using a callback to buffer EEG data.

```python
from muselsl.devices import create_device
import numpy as np

eeg_buffer = []

def handle_eeg(data, timestamps):
    eeg_buffer.append(data.copy())

device = create_device('00:1A:7D:DA:71:13', callback_eeg=handle_eeg)
device.connect()
device.start()

# Wait ~5 seconds for data
import time
time.sleep(5)

eeg = np.concatenate(eeg_buffer, axis=1)
print(f"Collected {eeg.shape} EEG samples")

device.stop()
device.disconnect()
```

--------------------------------

### Record PPG data with custom filename

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Example of recording PPG data and specifying a custom output file path.

```python
from muselsl import record

record(
    duration=120,
    filename='./data/ppg_session_001.csv',
    data_source='PPG'
)
```

--------------------------------

### Auto-Detect Device Type

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Example of programmatically identifying the connected Muse device model.

```python
from muselsl.devices import create_device
from muselsl.athena import Athena

device = create_device('00:1A:7D:DA:71:13', model='auto')
if device.connect():
    impl = device._impl
    if isinstance(impl, Athena):
        print("Muse S Gen 3 detected")
    else:
        print("Legacy Muse detected")
```

--------------------------------

### Record accelerometer with dejitter correction

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Example of recording accelerometer data with the dejitter option enabled.

```python
from muselsl import record

record(
    duration=30,
    data_source='ACC',
    dejitter=True
)
```

--------------------------------

### Record 60 seconds of EEG data

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Basic usage example for recording EEG data for 60 seconds.

```python
from muselsl import stream, record
import threading

# In one terminal/thread: start stream
# muselsl stream

# In another terminal: record data
from muselsl import record

record(duration=60)
```

--------------------------------

### Record with continuous saving

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Example of recording for a long duration with continuous saving enabled to manage memory.

```python
from muselsl import record

record(
    duration=3600,  # 1 hour
    filename='./long_eeg_session.csv',
    continuous=True
)
```

--------------------------------

### CSV output format example

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

The expected structure of the generated CSV file containing EEG channel data and timestamps.

```text
TP9,AF7,AF8,TP10,Right AUX,timestamps
-12.345,-5.678,3.456,2.109,-1.234,0.000
-12.456,-5.789,3.567,2.210,-1.345,0.004
...
```

--------------------------------

### Initialize and Connect with BleakBackend

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/backends.md

Demonstrates basic initialization, scanning, and connection using the Bleak backend.

```python
from muselsl import backends

adapter = backends.BleakBackend()
adapter.start()
devices = adapter.scan(timeout=10)
device = adapter.connect(address='00:1A:7D:DA:71:13', retries=2)
```

--------------------------------

### Muse.__init__

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Initializes a new Muse device instance with specified callbacks and configuration parameters.

```APIDOC
## Muse.__init__(address, callback_eeg=None, callback_control=None, callback_telemetry=None, callback_acc=None, callback_gyro=None, callback_ppg=None, backend='auto', interface=None, time_func=time, name=None, preset=None, disable_light=False)

### Description
Initializes the Muse device interface. This constructor sets up the connection parameters and callback functions for handling incoming data streams.

### Parameters
- **address** (str) - Required - MAC address of Muse device (e.g., '00:1A:7D:DA:71:13').
- **callback_eeg** (Callable) - Optional - Function called when EEG data arrives: `fn(data: np.ndarray[5, 12], timestamps: np.ndarray[12])`.
- **callback_control** (Callable) - Optional - Function called when control message arrives: `fn(message: str)`.
- **callback_telemetry** (Callable) - Optional - Function called when telemetry data arrives: `fn(timestamp: float, battery: float, fuel_gauge: float, adc_volt: int, temperature: int)`.
- **callback_acc** (Callable) - Optional - Function called when accelerometer data arrives: `fn(samples: np.ndarray[3, 3], timestamps: list[float])`.
- **callback_gyro** (Callable) - Optional - Function called when gyroscope data arrives: `fn(samples: np.ndarray[3, 3], timestamps: list[float])`.
- **callback_ppg** (Callable) - Optional - Function called when PPG (Muse 2 only) arrives: `fn(data: np.ndarray[3, 6], timestamps: np.ndarray[6])`.
- **backend** (str) - Optional - BLE backend: 'auto', 'bleak', 'gatt', 'bgapi', 'bluemuse'.
- **interface** (str) - Optional - Backend-specific interface: 'hci0' for gatt, COM port for bgapi.
- **time_func** (Callable) - Optional - Function to generate timestamps.
- **name** (str) - Optional - Device name for logging and auto-discovery.
- **preset** (int) - Optional - Device preset (20–21 for classic Muse 2016, 20–21 for Muse 2).
- **disable_light** (bool) - Optional - Disable indicator light on Muse S headband.
```

--------------------------------

### Implement Custom Backend Usage

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/backends.md

Full workflow for explicit backend initialization, device discovery, and connection management.

```python
from muselsl.backends import BleakBackend
from muselsl.muse import Muse

# Use bleak backend explicitly
adapter = BleakBackend()
adapter.start()

# Scan for devices
devices = adapter.scan(timeout=10)
print(f"Found {len(devices)} devices")

# Connect to device
device = adapter.connect(
    address=devices[0]['address'],
    retries=3,
    name=devices[0]['name']
)

if device:
    # Device is now connected; use with Muse
    adapter.stop()
else:
    print("Connection failed")
    adapter.stop()
```

--------------------------------

### Execute Full Auto-Detect Workflow

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

Demonstrates creating a device with auto-detection, connecting, and handling model-specific features like optics.

```python
from muselsl.devices import create_device

def handle_eeg(data, timestamps):
    print(f"EEG: {data.shape}")

def handle_optics(data, timestamps):
    print(f"Optics: {data.shape}")

# Create device (type unknown)
device = create_device(
    '00:1A:7D:DA:71:13',
    model='auto',
    callback_eeg=handle_eeg,
)

# Connect (probes and selects Muse or Athena)
if device.connect():
    # Now we can access implementation-specific attributes
    impl = device._impl
    
    if isinstance(impl, Athena):
        print("Connected to Muse S Gen 3 (Athena)")
        device.callback_optics = handle_optics
        device.enable_optics = True
        device.refresh_subscriptions()
    else:
        print("Connected to legacy Muse (2016 or 2)")
    
    device.start()
else:
    print("Connection failed")
```

--------------------------------

### Initialize Muse Device via Low-Level API

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/00_START_HERE.txt

Advanced usage for direct device control using the Muse class.

```python
from muselsl.muse import Muse
muse = Muse('00:1A:7D:DA:71:13', callback_eeg=my_callback)
muse.connect()
muse.start()
```

--------------------------------

### muselsl stream

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Starts streaming EEG data from a specific Muse device.

```APIDOC
## muselsl stream

### Description
Connects to a Muse device and begins streaming EEG data via LSL.

### Parameters
- **--address** (string) - Required - The MAC address of the Muse device to connect to.
```

--------------------------------

### Importing muselsl modules

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/module_index.md

Demonstrates the recommended high-level API imports, low-level device control imports, and common utility imports.

```python
# High-level API (recommended for most use cases)
from muselsl import stream, list_muses, record, record_direct, view

# Low-level API (device-specific control)
from muselsl.muse import Muse
from muselsl.athena import Athena
from muselsl.devices import create_device

# Utility imports
from muselsl.stream import find_muse
from muselsl.constants import *
```

--------------------------------

### Configure backend for streaming

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/INDEX.md

Specify the backend and interface when initiating a stream.

```python
from muselsl import stream
stream(address, backend='gatt', interface='hci0')
```

--------------------------------

### List Muse devices with default backend

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_stream.md

Iterate through discovered Muse devices using the default backend settings.

```python
from muselsl import list_muses

muses = list_muses()
for muse in muses:
    print(f"Name: {muse['name']}, MAC: {muse['address']}")
```

--------------------------------

### Integrate LSL outlets with stream callbacks

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/lsl_outlet.md

Configure outlets and define push callbacks to stream data samples in real-time.

```python
from muselsl import stream
from muselsl.lsl_outlet import build_outlet

# Internally in stream():
outlets = {}
for desc in muse.stream_descriptors():
    if enabled[desc.name]:
        outlets[desc.name] = build_outlet(desc, address)

# Callback pushes samples
def push(data, timestamps, outlet):
    for ii in range(data.shape[1]):
        outlet.push_sample(data[:, ii], timestamps[ii])

# Set up callbacks
muse.callback_eeg = partial(push, outlet=outlets['EEG'])
```

--------------------------------

### Downgrade pygatt Version

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Workaround for characteristic discovery issues by installing a specific compatible version of pygatt.

```bash
pip install pygatt==3.1.1
```

--------------------------------

### Enable Bluetooth via CLI

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Command to power on the Bluetooth adapter on Linux systems.

```bash
bluetoothctl power on
```

--------------------------------

### select_preset()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Sets the device preset configuration.

```APIDOC
## select_preset(preset: int | str = 21) -> None

### Description
Set device preset configuration.

### Parameters
- **preset** (int | str) - Optional - Preset ID. Classic Muse 2016 supports 20–21.
```

--------------------------------

### Select device preset

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Configures the device using a specific preset ID.

```python
def select_preset(self, preset: int | str = 'p1041') -> None
```

--------------------------------

### List Muse devices with specific backend

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_stream.md

Specify a custom backend and interface for device discovery.

```python
from muselsl import list_muses

muses = list_muses(backend='gatt', interface='hci0')
```

--------------------------------

### Select Preset

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Configures the device preset, typically applied during connection.

```python
def select_preset(self, preset: int | str = 21) -> None
```

--------------------------------

### Initialize Muse Class

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Constructor for the Muse class, defining callbacks for various data streams and configuration for the BLE backend.

```python
class Muse:
    def __init__(
        self,
        address: str,
        callback_eeg: Callable[[np.ndarray, np.ndarray], None] | None = None,
        callback_control: Callable[[str], None] | None = None,
        callback_telemetry: Callable[[float, float, float, float, float], None] | None = None,
        callback_acc: Callable[[np.ndarray, list[float]], None] | None = None,
        callback_gyro: Callable[[np.ndarray, list[float]], None] | None = None,
        callback_ppg: Callable[[np.ndarray, np.ndarray], None] | None = None,
        backend: str = 'auto',
        interface: str | None = None,
        time_func: Callable[[], float] = time,
        name: str | None = None,
        preset: int | None = None,
        disable_light: bool = False,
    ) -> None
```

--------------------------------

### Record with auto-discovery

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Initiate a 120-second recording session by searching for a device name and saving to a specific file path.

```python
from muselsl import record_direct

record_direct(
    duration=120,
    address='',
    name='Muse-41D2',
    filename='./session_001.csv'
)
```

--------------------------------

### connect() Method Signature

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

Method signature for establishing a connection and probing device type.

```python
def connect(self, interface: str | None = None, retries: int = 0) -> bool
```

--------------------------------

### Stream Alternate Sensor Data via CLI

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Enable PPG, accelerometer, and gyroscope data streams using command-line arguments.

```Bash
muselsl stream --ppg --acc --gyro
```

--------------------------------

### Configure Display and Viewer Settings

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/constants.md

Sets decimation and buffer duration for data visualization.

```python
VIEW_SUBSAMPLE = 2    # Decimate by 2x when displaying
VIEW_BUFFER = 12      # Seconds of data to keep in display buffer
```

--------------------------------

### Configure Logging

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/helper.md

Initializes process-wide logging using the standard logging module.

```python
def configure_logging(level: int) -> None
```

```python
from muselsl.helper import configure_logging
import logging

configure_logging(logging.DEBUG)
```

--------------------------------

### Stream from Muse S with optics

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/INDEX.md

Configure streaming specifically for Muse S hardware with optics enabled.

```bash
muselsl stream --model athena --optics --disable-light
```

--------------------------------

### Initialize Athena class

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Constructor for the Athena device interface, accepting callbacks for various data streams and configuration parameters.

```python
class Athena:
    def __init__(
        self,
        address: str,
        callback_eeg: Callable[[np.ndarray, np.ndarray], None] | None = None,
        callback_control: Callable[[str], None] | None = None,
        callback_telemetry: Callable[[float, float, float, float, float], None] | None = None,
        callback_acc: Callable[[np.ndarray, list[float]], None] | None = None,
        callback_gyro: Callable[[np.ndarray, list[float]], None] | None = None,
        callback_optics: Callable[[np.ndarray, np.ndarray], None] | None = None,
        backend: str = 'auto',
        interface: str | None = None,
        time_func: Callable[[], float] = time,
        name: str | None = None,
        preset: int | str | None = None,
        disable_light: bool = False,
    ) -> None
```

--------------------------------

### ask_device_info()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Requests detailed device firmware and hardware information.

```APIDOC
## ask_device_info() -> None

### Description
Request detailed device firmware and hardware information. Response is received via callback_control.
```

--------------------------------

### connect()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Establishes a BLE connection to the Muse device and subscribes to enabled data streams.

```APIDOC
## connect(interface: str | None = None, retries: int = 0) -> bool

### Description
Establish BLE connection to device and subscribe to enabled data streams.

### Parameters
- **interface** (str | None) - Optional - Overrides constructor interface if provided.
- **retries** (int) - Optional - Number of retry attempts on connection failure. Use -1 for infinite retries.

### Returns
- **bool** - True if connected successfully, False if connection failed after all retries exhausted.
```

--------------------------------

### Athena Class Initialization

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Initializes the Athena device connection and registers data callbacks.

```APIDOC
## Athena(address, callback_optics=None, callback_eeg=None, callback_acc=None, callback_gyro=None, callback_telemetry=None)

### Description
Initializes the Athena device interface. Users provide callback functions to handle incoming data streams.

### Parameters
- **address** (str) - Required - The MAC address of the Athena device.
- **callback_optics** (callable) - Optional - Function to handle fNIRS data.
- **callback_eeg** (callable) - Optional - Function to handle EEG data.
- **callback_acc** (callable) - Optional - Function to handle accelerometer data.
- **callback_gyro** (callable) - Optional - Function to handle gyroscope data.
- **callback_telemetry** (callable) - Optional - Function to handle battery and telemetry data.
```

--------------------------------

### View data in real-time

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/REFERENCE.md

Visualize streaming data in real-time.

```bash
muselsl stream

muselsl view --window 5 --scale 100
```

--------------------------------

### Use experimental version 2 viewer

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_view.md

Enables the high-performance GPU-accelerated viewer. Requires optional vispy and mne dependencies.

```python
# First, install optional dependencies:
# pip install vispy mne

from muselsl import view

view(version=2)
```

--------------------------------

### create_device(address, model='auto', **kwargs)

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

Factory function to instantiate the correct device class (Muse or Athena) based on model selection or auto-detection.

```APIDOC
## create_device(address, model='auto', **kwargs)

### Description
Instantiates a device object for Muse hardware. It supports manual model selection or automatic detection to determine the correct device class (Muse or Athena).

### Parameters
- **address** (str) - Required - MAC address of the Muse device.
- **model** (str) - Optional - Default: 'auto'. Device model: 'auto' (probe at connect time), 'legacy' (classic Muse/Muse 2), or 'athena' (Muse S Gen 3).
- **kwargs** (dict) - Optional - Additional keyword arguments passed to the constructor (e.g., backend, interface, callback_*, enable_*, preset, disable_light, name, time_func).

### Return Type
- Returns a `Muse` instance if `model='legacy'`.
- Returns an `Athena` instance if `model='athena'`.
- Returns an `_AutoSelectingDevice` instance if `model='auto'`.

### Raises
- `ValueError` if `model` is not one of: 'auto', 'legacy', 'athena'.
- `RuntimeError` if `model='auto'` and the device has neither Athena nor legacy EEG characteristics.
```

--------------------------------

### Configure Timing and LSL Parameters

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/constants.md

Defines timeouts and buffer sizes for device scanning and LSL stream handling.

```python
LIST_SCAN_TIMEOUT = 10.5      # Seconds to scan for devices
AUTO_DISCONNECT_DELAY = 3     # Seconds of inactivity before disconnect
RETRY_SLEEP_TIMEOUT = 1       # Seconds to wait between connection retries

LSL_SCAN_TIMEOUT = 5          # Seconds to wait for LSL stream
LSL_BUFFER = 360              # Seconds of buffering in LSL inlet
```

--------------------------------

### Athena.__init__

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Initializes the Athena device interface for a specific Muse S Gen 3 device, configuring data callbacks and connection parameters.

```APIDOC
## Athena.__init__

### Description
Initializes the Athena device interface. This constructor sets up the connection to the Muse S Gen 3 device and registers callback functions for various data streams.

### Parameters
- **address** (str) - Required - MAC address of Muse S Gen 3 device.
- **callback_eeg** (Callable) - Optional - Function called on EEG data: `fn(data: np.ndarray[4, 4], timestamps: np.ndarray[4])`.
- **callback_control** (Callable) - Optional - Function called on control messages: `fn(message: str)`.
- **callback_telemetry** (Callable) - Optional - Function called on telemetry: `fn(timestamp, battery, fuel_gauge, adc_volt, temperature)`.
- **callback_acc** (Callable) - Optional - Function called on accelerometer: `fn(samples: np.ndarray[3, 3], timestamps: list[float])`.
- **callback_gyro** (Callable) - Optional - Function called on gyroscope: `fn(samples: np.ndarray[3, 3], timestamps: list[float])`.
- **callback_optics** (Callable) - Optional - Function called on optical (fNIRS) data: `fn(data: np.ndarray[16, N], timestamps: np.ndarray[N])`.
- **backend** (str) - Optional - BLE backend: 'auto', 'bleak', 'gatt', or 'bgapi'.
- **interface** (str) - Optional - Backend-specific interface.
- **time_func** (Callable) - Optional - Timestamp generation function.
- **name** (str) - Optional - Device name.
- **preset** (int | str) - Optional - Preset ID (e.g., 'p1041').
- **disable_light** (bool) - Optional - Disable indicator light on headband.
```

--------------------------------

### Stream EEG from first available device

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_stream.md

Uses list_muses to find available devices and initiates a stream from the first one found.

```python
from muselsl import stream, list_muses

muses = list_muses()
if muses:
    stream(muses[0]['address'])
```

--------------------------------

### muselsl record_direct command usage

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Basic command structure for recording data directly from a Muse device.

```bash
muselsl record_direct [options]
```

--------------------------------

### Stream and Record via CLI

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/00_START_HERE.txt

Basic command-line interface usage for streaming and recording EEG data.

```bash
muselsl stream
```

```bash
muselsl record --duration 60
```

--------------------------------

### muselsl list

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Lists all available Muse devices detected on the system.

```APIDOC
## muselsl list

### Description
Lists available Muse devices on the system. This command scans for devices and displays their names and MAC addresses.

### Options
- **-b, --backend** (string) - Optional - BLE backend: auto, bleak, gatt, bgapi, bluemuse
- **-i, --interface** (string) - Optional - Backend-specific interface: hci0 (gatt), COM port (bgapi)
- **-l, --log** (string) - Optional - Logging level (default: info)
```

--------------------------------

### Connect to Muse Device

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Establishes a BLE connection and subscribes to data streams. Requires a valid MAC address and optional callback functions.

```python
def connect(self, interface: str | None = None, retries: int = 0) -> bool
```

```python
from muselsl.muse import Muse

def handle_eeg(data, timestamps):
    print(f"EEG: {data.shape}, ts: {timestamps}")

muse = Muse('00:1A:7D:DA:71:13', callback_eeg=handle_eeg)
if muse.connect():
    print("Connected")
else:
    print("Failed to connect")
```

--------------------------------

### Low-Level Device Control

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/module_index.md

Manually initializes and controls a Muse device connection.

```python
from muselsl.devices import create_device

device = create_device('00:1A:7D:DA:71:13', model='auto')
device.connect()
device.start()
```

--------------------------------

### ask_reset()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Sends a reset command to the device.

```APIDOC
## ask_reset() -> None

### Description
Send undocumented reset command ('*1') to device.
```

--------------------------------

### Create LSL outlets for Muse streams

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/lsl_outlet.md

Iterate through stream descriptors to initialize and store LSL outlets for a specific Muse device.

```python
from muselsl.lsl_outlet import build_outlet
from muselsl.muse import Muse

muse = Muse('00:1A:7D:DA:71:13')
descriptors = muse.stream_descriptors()

outlets = {}
for desc in descriptors:
    outlet = build_outlet(desc, '00:1A:7D:DA:71:13')
    outlets[desc.name] = outlet
    print(f"Created {desc.name} outlet: {desc.n_channels} channels @ {desc.rate} Hz")
```

--------------------------------

### Stream Data via Python API

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/00_START_HERE.txt

Standard Python workflow to discover available Muse devices and initiate a stream.

```python
from muselsl import stream, list_muses
muses = list_muses()
stream(muses[0]['address'])
```

--------------------------------

### Force legacy Muse connection

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

Instantiate a legacy Muse device directly without probing for Athena characteristics.

```python
from muselsl.devices import create_device

device = create_device('00:1A:7D:DA:71:13', model='legacy')
device.connect()
```

--------------------------------

### Access CLI commands

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/INDEX.md

Common command-line interface operations for managing devices and streams.

```bash
muselsl list
muselsl stream --help
muselsl record --help
```

--------------------------------

### connect(interface: str | None = None, retries: int = 0) -> bool

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Establishes a BLE connection to the Athena device and subscribes to multiplexed data streams.

```APIDOC
## connect(interface: str | None = None, retries: int = 0) -> bool

### Description
Establishes a BLE connection to the Athena device and subscribes to multiplexed data streams (DATA_1, DATA_2, CONTROL).

### Parameters
- **interface** (str | None) - Optional - BLE adapter interface.
- **retries** (int) - Optional - Number of connection retries.

### Returns
- **bool** - True if successful, False otherwise.
```

--------------------------------

### Define Accelerometer and Gyroscope Callbacks

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Signatures for motion sensor callbacks, consistent with legacy Muse devices.

```python
def callback_acc(samples: np.ndarray, timestamps: list[float]) -> None:
    # samples: shape (3, 3), units: g
    pass

def callback_gyro(samples: np.ndarray, timestamps: list[float]) -> None:
    # samples: shape (3, 3), units: dps
    pass
```

--------------------------------

### list_muses()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_stream.md

Discovers and returns a list of available Muse BLE devices on the system.

```APIDOC
## list_muses(backend='auto', interface=None)

### Description
Discovers and returns a list of available Muse BLE devices on the system. It scans for devices and filters results to those with 'Muse' in their name.

### Parameters
- **backend** (str) - Optional - Bluetooth backend: 'auto', 'bleak', 'gatt', 'bgapi', or 'bluemuse'. Defaults to 'auto'.
- **interface** (str) - Optional - Backend-specific interface/port (e.g., 'hci0' for gatt, COM port for bgapi). Defaults to None.

### Return Type
- **list[dict]** - A list of dictionaries, where each dictionary contains 'name' (str) and 'address' (str) keys. Returns an empty list if no devices are found.

### Raises
- **pygatt.exceptions.BLEError** - If the pygatt adapter fails and bluetoothctl is unavailable.
- **ModuleNotFoundError** - If using the bluetoothctl backend without pexpect installed.

### Example Usage
```python
from muselsl import list_muses

# List all Muses with default backend
muses = list_muses()
for muse in muses:
    print(f"Name: {muse['name']}, MAC: {muse['address']}")

# List Muses with specific backend
muses = list_muses(backend='gatt', interface='hci0')
```
```

--------------------------------

### View EEG data with muselsl

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Commands to launch the real-time EEG viewer with various configuration options.

```bash
muselsl view [options]
```

```bash
muselsl view
```

```bash
muselsl view --window 10 --scale 50 --figure 20x12
```

```bash
muselsl view --version 2
```

--------------------------------

### Record with specific backend

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Initiate a recording session specifying the GATT backend and the hci0 interface.

```python
from muselsl import record_direct

record_direct(
    duration=60,
    address='00:1A:7D:DA:71:13',
    backend='gatt',
    interface='hci0'
)
```

--------------------------------

### Force Athena connection with callbacks

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

Instantiate an Athena device directly and provide custom callbacks for data handling.

```python
from muselsl.devices import create_device

def handle_eeg(data, timestamps):
    print(f"EEG: {data.shape}")

device = create_device(
    '00:1A:7D:DA:71:13',
    model='athena',
    callback_eeg=handle_eeg,
)
device.connect()
```

--------------------------------

### AutoSelectingDevice Class Definition

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

The internal wrapper class structure for handling device selection.

```python
class _AutoSelectingDevice:
    def __init__(self, address: str, **kwargs) -> None
    def connect(self, interface: str | None = None, retries: int = 0) -> bool
    def stream_descriptors(self) -> list[StreamDescriptor]
    def __getattr__(self, name: str) -> Any
    def __setattr__(self, name: str, value: Any) -> None
```

--------------------------------

### Record Alternate Data Sources via CLI

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Record data from a specific sensor type. Only one data type can be recorded per process.

```Bash
muselsl record --type ACC
```

--------------------------------

### ask_control()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Requests device control status.

```APIDOC
## ask_control() -> None

### Description
Request device control status (name, battery, preset, etc.). Response is received via callback_control.
```

--------------------------------

### View with Qt5 backend

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_view.md

Specifies a custom matplotlib backend for the version 1 viewer.

```python
from muselsl import view

view(
    backend='Qt5Agg',
    window=8,
    scale=75,
)
```

--------------------------------

### Configure Linux BLE Permissions

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Grant necessary network capabilities to hcitool to resolve BLE scan permission errors on Linux.

```bash
sudo setcap 'cap_net_raw,cap_net_admin+eip' `which hcitool`
```

--------------------------------

### Record directly by MAC address

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_record.md

Initiate a 60-second recording session using a specific device MAC address.

```python
from muselsl import record_direct

record_direct(
    duration=60,
    address='00:1A:7D:DA:71:13'
)
```

--------------------------------

### Request device info

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_athena.md

Requests firmware and hardware information from the device.

```python
def ask_device_info(self) -> None
```

--------------------------------

### view(window=5, scale=100, refresh=0.2, figure='15x6', version=1, backend='TkAgg')

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_view.md

Launches an interactive real-time viewer for EEG data from an active LSL stream. This function is blocking until the viewer window is closed.

```APIDOC
## view()

### Description
Launches an interactive real-time viewer for EEG data from an active LSL stream. This function is blocking until the viewer window is closed by the user.

### Signature
`view(window: float = 5, scale: float = 100, refresh: float = 0.2, figure: str = '15x6', version: int = 1, backend: str = 'TkAgg') -> None`

### Parameters
- **window** (float) - Optional - Time window to display on screen, in seconds.
- **scale** (float) - Optional - Amplitude scale in microvolts (µV) per division.
- **refresh** (float) - Optional - GUI refresh rate in seconds.
- **figure** (str) - Optional - Window size as 'WIDTHxHEIGHT' in inches.
- **version** (int) - Optional - Viewer implementation: 1 (stable, matplotlib+pyplot), 2 (experimental, vispy+mne).
- **backend** (str) - Optional - Matplotlib backend for version 1 (e.g., 'TkAgg', 'Qt5Agg', 'MacOSX'). Ignored for version 2.

### Return Type
None

### Requirements
- An active LSL stream of type 'EEG' must be running.
- Stream must have 5 channels with standard Muse labels: TP9, AF7, AF8, TP10, Right AUX.
- Version 2 requires optional dependencies: `pip install vispy mne`
```

--------------------------------

### Detect device type automatically

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/INDEX.md

Instantiate a device object with automatic model detection.

```python
from muselsl.devices import create_device
device = create_device('00:1A:7D:DA:71:13', model='auto')
device.connect()
```

--------------------------------

### BleakBackend.connect

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/backends.md

Establishes a connection to a specific BLE device using its MAC address.

```APIDOC
## connect(address: str, retries: int, name: str | None = None)

### Description
Attempts to connect to a BLE device identified by the provided MAC address.

### Parameters
- **address** (str) - Required - The MAC address of the target device.
- **retries** (int) - Required - Number of connection retry attempts.
- **name** (str | None) - Optional - Device name for logging and discovery purposes.

### Returns
- **BleakDevice | None** - Returns a BleakDevice instance on success, or None if the connection fails.
```

--------------------------------

### Connect to BLE Device

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/backends.md

Establishes a connection with exponential backoff and automatic address refreshing.

```python
def connect(self, retries: int) -> bool
```

--------------------------------

### Define PPG Callback

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Handles PPG data for Muse 2 devices, providing 3 channels with 6 samples per packet.

```python
def callback_ppg(data: np.ndarray, timestamps: np.ndarray) -> None:
    """
    data: shape (3, 6), dtype float32
        3 channels (PPG1, PPG2, PPG3) × 6 samples per packet
        Units: mmHg (assuming calibration)
    timestamps: shape (6,), dtype float32
        Timestamps of each sample
    """
    pass
```

--------------------------------

### Request Control and Device Info

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_muse.md

Methods to query device status, battery, and firmware details.

```python
def ask_control(self) -> None
```

```python
def ask_device_info(self) -> None
```

--------------------------------

### Stream EEG data from Muse

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Commands to initiate an LSL stream from a Muse device.

```bash
$ muselsl list
$ muselsl stream  
$ muselsl stream --name YOUR_DEVICE_NAME
$ muselsl stream --address YOUR_DEVICE_ADDRESS
```

--------------------------------

### Visualize and record streaming data

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/README.md

Commands for viewing real-time data or recording it to a CSV file.

```bash
$ muselsl view
$ muselsl view --version 2
$ muselsl record --duration 60  
$ muselsl record_direct --duration 60
```

--------------------------------

### muselsl record command usage

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/cli_reference.md

Basic command structure for recording data from an active LSL stream.

```bash
muselsl record [options]
```

--------------------------------

### Auto-discover and stream with retries

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_stream.md

Initiates a stream by auto-discovering a device by name, with custom retry logic and LSL time synchronization enabled.

```python
from muselsl import stream

stream(
    address='',
    name='Muse-41D2',
    retries=5,
    lsl_time=True
)
```

--------------------------------

### record_direct()

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/module_index.md

Records data directly from a Muse device via BLE.

```APIDOC
## record_direct(duration, address, filename=None, backend='auto', interface=None, name=None)

### Description
Establishes a direct connection to a Muse device and records data to a CSV file.

### Parameters
- **duration** (float) - Required - Duration of the recording in seconds.
- **address** (str) - Required - The BLE address of the device.
- **filename** (str) - Optional - Path to the output CSV file.
- **backend** (str) - Optional - The BLE backend to use.
- **interface** (str) - Optional - The network interface.
- **name** (str) - Optional - The device name.
```

--------------------------------

### View with custom time window and scale

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_view.md

Customizes the visualization window duration, amplitude scale, and refresh rate.

```python
from muselsl import view

view(
    window=10,      # Show 10 seconds of data
    scale=50,       # 50µV per division (more zoomed in)
    refresh=0.1,    # Faster refresh
)
```

--------------------------------

### Define create_device signature

Source: https://github.com/alexandrebarachant/muse-lsl/blob/master/_autodocs/api_devices.md

The factory function signature for instantiating Muse or Athena device classes.

```python
def create_device(
    address: str,
    model: str = 'auto',
    **kwargs
) -> Muse | Athena | _AutoSelectingDevice
```