Bose-SoundTouch/docs/BASS-CONTROLS.md

Bass Control Guide

Overview

The Bose SoundTouch Go client provides comprehensive bass control functionality through the GET /bass and POST /bass endpoints. This feature allows you to adjust bass levels from -9 (maximum bass cut) to +9 (maximum bass boost) with full validation and safety features.

Implementation Status

✅ Complete - All bass control functionality implemented and tested

• Bass level retrieval with GetBass()
• Bass level adjustment with SetBass()
• Increment/decrement methods with safety limits
• CLI flags for easy bass management
• Real device validation with SoundTouch hardware
• Comprehensive error handling and range validation

API Endpoints

GET /bass

Purpose: Retrieve current bass settings

Response Format:

<bass deviceID="ABCD1234EFGH">
  <targetbass>3</targetbass>
  <actualbass>3</actualbass>
</bass>

Fields:

• targetbass - The desired bass level (-9 to +9)
• actualbass - The current actual bass level (may differ during adjustment)
• deviceID - Unique device identifier

POST /bass

Purpose: Set bass level

Request Format:

<bass>5</bass>

Valid Range: -9 to +9

• -9 to -1: Bass cut (reduces bass frequencies)
• 0: Neutral/flat bass response
• +1 to +9: Bass boost (enhances bass frequencies)

Response: HTTP 200 OK (no body) on success

Client Library Usage

Basic Bass Control

import "github.com/user_account/bose-soundtouch/pkg/client"

// Create client
config := client.ClientConfig{
    Host: "192.168.1.100",
    Port: 8090,
}
c := client.NewClient(config)

// Get current bass level
bass, err := c.GetBass()
if err != nil {
    fmt.Printf("Failed to get bass: %v\n", err)
}

fmt.Printf("Bass Level: %d (%s)\n", bass.GetLevel(), bass.String())

// Set bass level
err = c.SetBass(3)
if err != nil {
    fmt.Printf("Failed to set bass: %v\n", err)
}

Bass Information Methods

// Get bass level information
bass, err := c.GetBass()
if err != nil {
    return err
}

// Access bass level details
level := bass.GetLevel()          // Target bass level
actual := bass.GetActualLevel()   // Current actual level
isAtTarget := bass.IsAtTarget()   // true if target == actual

// Bass categorization
isBoost := bass.IsBassBoost()     // true if level > 0
isCut := bass.IsBassCut()         // true if level < 0
isFlat := bass.IsFlat()           // true if level == 0

// Human-readable descriptions
levelName := models.GetBassLevelName(level)     // "Slightly High", "Very Low", etc.
category := models.GetBassLevelCategory(level)  // "Bass Boost", "Bass Cut", "Flat"

Safe Bass Control

// SetBassSafe automatically clamps values to valid range
err := c.SetBassSafe(15)  // Will be clamped to +9
err = c.SetBassSafe(-15)  // Will be clamped to -9

// Increment/decrement with automatic clamping
newBass, err := c.IncreaseBass(2)  // Increase by 2, clamp if needed
newBass, err := c.DecreaseBass(1)  // Decrease by 1, clamp if needed

Validation and Limits

import "github.com/user_account/bose-soundtouch/pkg/models"

// Validate bass level before setting
if models.ValidateBassLevel(level) {
    err := c.SetBass(level)
}

// Clamp to valid range
safeLevel := models.ClampBassLevel(100)  // Returns +9

// Constants
fmt.Printf("Bass range: %d to %d\n", models.BassLevelMin, models.BassLevelMax)  // -9 to 9
fmt.Printf("Default: %d\n", models.BassLevelDefault)  // 0

CLI Usage

Basic Commands

# Get current bass level
soundtouch-cli -host 192.168.1.100 -bass

# Set specific bass level
soundtouch-cli -host 192.168.1.100 -set-bass 3
soundtouch-cli -host 192.168.1.100 -set-bass -5

# Increment/decrement bass
soundtouch-cli -host 192.168.1.100 -inc-bass 1
soundtouch-cli -host 192.168.1.100 -dec-bass 2

Real Examples

# Check current bass settings
soundtouch-cli -host 192.168.1.100 -bass
# Output: Bass Level: 0 (Neutral)
#         Category: Flat

# Set bass boost
soundtouch-cli -host 192.168.1.100 -set-bass 6
# Output: ✓ Bass set to 6 (High)

# Reset to neutral
soundtouch-cli -host 192.168.1.100 -set-bass 0
# Output: ✓ Bass set to 0 (Neutral)

# Gradual bass adjustment
soundtouch-cli -host 192.168.1.100 -inc-bass 2
# Output: ✓ Bass increased to 2 (Slightly High)

CLI Flags

Flag	Description	Range	Default
-bass	Get current bass level	N/A	N/A
-set-bass <level>	Set bass level	-9 to +9	N/A
-inc-bass <amount>	Increase bass	1-3	1
-dec-bass <amount>	Decrease bass	1-3	1

Safety Features

• Validation: Invalid ranges are rejected before sending to device
• Clamping: Values are automatically clamped to valid range with -safe methods
• Limits: Increment/decrement amounts are limited for safety (max 3 per command)
• Error Messages: Clear error messages for invalid inputs

Bass Level Reference

Level Descriptions

Level	Name	Category	Description
-9 to -7	Very Low	Bass Cut	Maximum bass reduction
-6 to -4	Low	Bass Cut	Moderate bass reduction
-3 to -1	Slightly Low	Bass Cut	Mild bass reduction
0	Neutral	Flat	No bass adjustment
1 to 3	Slightly High	Bass Boost	Mild bass enhancement
4 to 6	High	Bass Boost	Moderate bass enhancement
7 to 9	Very High	Bass Boost	Maximum bass enhancement

Practical Usage Guidelines

For Different Music Genres:

• Classical/Acoustic: -1 to +1 (subtle adjustments)
• Rock/Pop: +2 to +4 (moderate bass boost)
• Electronic/Hip-Hop: +4 to +6 (strong bass enhancement)
• Vocals/Podcasts: -2 to 0 (reduce bass for clarity)

For Different Environments:

• Small rooms: -1 to +2 (avoid overwhelming bass)
• Large rooms: +3 to +6 (compensate for space)
• Near-field listening: 0 to +2 (balanced response)
• Background music: -2 to +1 (non-intrusive)

Integration Examples

Smart Bass Management

func adjustBassForContent(client *client.Client, contentType string) error {
    var targetBass int
    
    switch contentType {
    case "music":
        targetBass = 3  // Moderate bass boost for music
    case "podcast":
        targetBass = -1 // Slight bass cut for voice clarity
    case "movie":
        targetBass = 5  // Strong bass for movie experience
    default:
        targetBass = 0  // Neutral for unknown content
    }
    
    return client.SetBass(targetBass)
}

Bass Presets

type BassPreset struct {
    Name  string
    Level int
}

var bassPresets = []BassPreset{
    {"Flat", 0},
    {"Voice", -2},
    {"Music", 3},
    {"Movies", 5},
    {"Heavy", 7},
}

func applyBassPreset(client *client.Client, presetName string) error {
    for _, preset := range bassPresets {
        if preset.Name == presetName {
            return client.SetBass(preset.Level)
        }
    }
    return fmt.Errorf("preset not found: %s", presetName)
}

Gradual Bass Adjustment

func gradualBassChange(client *client.Client, targetLevel int, stepSize int) error {
    currentBass, err := client.GetBass()
    if err != nil {
        return err
    }
    
    current := currentBass.GetLevel()
    
    for current != targetLevel {
        var step int
        if targetLevel > current {
            step = min(stepSize, targetLevel-current)
            _, err = client.IncreaseBass(step)
        } else {
            step = min(stepSize, current-targetLevel)
            _, err = client.DecreaseBass(step)
        }
        
        if err != nil {
            return err
        }
        
        // Update current level
        currentBass, err = client.GetBass()
        if err != nil {
            return err
        }
        current = currentBass.GetLevel()
        
        time.Sleep(200 * time.Millisecond) // Brief pause between adjustments
    }
    
    return nil
}

Error Handling and Troubleshooting

Common Error Scenarios

1. Invalid Range Errors

err := client.SetBass(15)
// Error: invalid bass level: 15 (must be between -9 and 9)

Solution: Use valid range (-9 to +9) or SetBassSafe() for auto-clamping.

2. Device Connection Errors

soundtouch-cli -host 192.168.1.100 -bass
# Error: failed to get bass: API request failed with status 404

Solutions:

• Verify device IP address and port
• Check network connectivity
• Ensure device supports bass control

3. Device-Specific Behavior

Some devices may:

• Override bass settings based on source or content
• Have limited bass range despite API acceptance
• Reset bass to default when changing sources

Solutions:

• Test bass control with different audio sources
• Check device capabilities and documentation
• Implement retry logic for critical applications

Debugging Tips

1. Check Current Settings

   soundtouch-cli -host <ip> -bass
   

2. Test Basic Functionality

   soundtouch-cli -host <ip> -set-bass 0    # Reset to neutral
   soundtouch-cli -host <ip> -set-bass 1    # Small positive adjustment
   soundtouch-cli -host <ip> -bass          # Verify change
   

3. Validate Range Handling

   soundtouch-cli -host <ip> -set-bass 15   # Should fail validation
   soundtouch-cli -host <ip> -set-bass -15  # Should fail validation
   

Testing

Unit Tests

Run bass control tests:

go test ./pkg/models -v -run ".*Bass.*"
go test ./pkg/client -v -run ".*Bass.*"

Integration Tests

Test with real hardware:

SOUNDTOUCH_TEST_HOST=192.168.1.100 go test ./pkg/client -v -run ".*Bass.*Integration.*"

Manual Testing

# Complete bass control test sequence
soundtouch-cli -discover
soundtouch-cli -host <discovered-ip> -bass
soundtouch-cli -host <discovered-ip> -set-bass 3
soundtouch-cli -host <discovered-ip> -inc-bass 1
soundtouch-cli -host <discovered-ip> -dec-bass 2
soundtouch-cli -host <discovered-ip> -bass  # Verify final state

Performance

Typical Response Times

• GetBass(): 50-150ms
• SetBass(): 100-300ms
• IncreaseBass()/DecreaseBass(): 200-500ms (includes GET + SET + GET)

Best Practices

1. Cache Current State: Minimize GET requests by tracking state locally
2. Batch Operations: Group multiple bass changes when possible
3. Validate Locally: Use client-side validation before API calls
4. Handle Timeouts: Implement appropriate timeout handling for network operations

Device Compatibility

Tested Devices

• SoundTouch 10: ✅ Full bass control support
• SoundTouch 20: ✅ Full bass control support
• SoundTouch 30: Expected to work (similar API)

Known Limitations

1. Source Dependencies: Some sources may override bass settings
2. Content-Based Adjustment: Device may auto-adjust bass based on audio content
3. Firmware Variations: Different firmware versions may behave differently

Compatibility Notes

• Bass control availability depends on device capabilities
• Some devices may have restricted bass ranges
• Certain audio sources may disable manual bass control

Related Documentation

• API Endpoints Overview - Complete API reference
• Volume Controls - Related audio control documentation
• Client Usage Examples - CLI implementation reference
• Models - Bass model implementation

API Compliance

XML Format Requirements

The implementation follows the official SoundTouch API:

• Uses simple <bass>level</bass> structure for requests
• Handles <bass><targetbass> and <actualbass> in responses
• Validates range (-9 to +9) as per specification
• Provides proper error handling for invalid values

Standards Compliance

• HTTP Methods: Proper GET for retrieval, POST for setting
• Content-Type: Correct application/xml headers
• Error Codes: Standard HTTP status codes
• XML Encoding: UTF-8 encoding as expected by devices

---

Implementation Date: 2026-01-09
Status: ✅ Complete and tested
Real Device Validation: SoundTouch 10, SoundTouch 20
API Compliance: Full compliance with SoundTouch Web API specification