### Implement Smart Volume Ramping

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Use `SmartVolumeUp` and `SmartVolumeFinished` actions for two-speed volume ramping. This allows for slow steps when a button is held briefly and fast steps after a threshold is met. The `plugin.smart_vol_up_start` variable tracks the start time for the ramping logic.

```python
# client.py  (EventGhost action objects, called via macros)
# Typical EventGhost macro binding for a held remote button:

# On button press — start ramping up:
#   Action: SmartVolumeUp  zone='Active Zone'  step1=0.5  step2=2.0  wait=2.0
#   Effect: increases by 0.5 dB per event for first 2 s, then 2.0 dB per event

# On button release — reset the timer:
#   Action: SmartVolumeFinished
#   Effect: clears smart_vol_up_start / smart_vol_down_start so next press starts fresh

# Python script equivalent:
import datetime, time

plugin.smart_vol_up_start = None   # reset first
# simulate 5 rapid presses:
for _ in range(5):
    if plugin.smart_vol_up_start is None:
        plugin.smart_vol_up_start = datetime.datetime.now()
    diff = datetime.datetime.now() - plugin.smart_vol_up_start
    step = 0.5 if diff.seconds < 2.0 else 2.0
    from yamaha import increase_volume
    increase_volume(plugin, zone=plugin.active_zone, inc=step)
    time.sleep(0.2)

# After button release:
plugin.smart_vol_up_start = None
plugin.smart_vol_down_start = None
```

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

### Change Input Source

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Switch the active input source on any zone using `change_source`. You can also cycle through a custom list of inputs, which involves getting the current source, finding its index in the list, and then selecting the next one.

```python
from yamaha import change_source

# Select HDMI1 on Main Zone:
change_source(plugin, source='HDMI1', zone=0)

# Select Tuner on Zone 2 (note: internal name is 'TUNER'):
change_source(plugin, source='TUNER', zone=2)

# --- Cycle inputs (via EventGhost action, equivalent logic) ---
from yamaha import get_source_name
from helpers import convert_zone_to_int

izone = convert_zone_to_int(plugin, 'Active Zone', convert_active=True)
# izone resolves to plugin.active_zone (e.g. 0 for Main Zone)

my_inputs = ['HDMI1', 'HDMI2', 'AV1', 'TUNER']
current = get_source_name(plugin, izone)   # e.g. 'HDMI1'
idx = my_inputs.index(current) if current in my_inputs else -1
next_idx = (idx + 1) % len(my_inputs)
change_source(plugin, my_inputs[next_idx], izone)
print "Switched to", my_inputs[next_idx]
```

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

### Send and Receive Raw XML Commands

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

These functions allow sending arbitrary YNC XML commands to the receiver and retrieving responses. Examples include turning on the main zone power and getting basic status information.

```python
# yamaha_xml.py
from yamaha_xml import put_xml, get_xml, zone_put_xml

# PUT example – turn Main Zone power on:
put_xml(plugin, '<Main_Zone><Power_Control><Power>On</Power></Power_Control></Main_Zone>')

# GET example – read basic status of Main Zone:
xml_str = get_xml(plugin, '<Main_Zone><Basic_Status>GetParam</Basic_Status></Main_Zone>')
print xml_str
# <YAMAHA_AV rsp="GET" RC="0"><Main_Zone><Basic_Status>...volume, input, mute...</Basic_Status></Main_Zone></YAMAHA_AV>
```

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

### Send Any Command

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Send an arbitrary YNC PUT or GET command and optionally return the result. This is useful for controlling features not explicitly exposed by other plugin functions.

```APIDOC
## Send Any Command — `send_any` / `SendAnyCommand`

### Description
Send an arbitrary YNC PUT or GET command and optionally return the result.

### Method
`send_any(plugin, value, action)`

### Parameters
#### Path Parameters
- **plugin**: The EventGhost plugin instance.
- **value** (string) - Required - The XML command string to send.
- **action** (string) - Required - The type of action, either 'Put' or 'Get'.

### Request Example
```python
from yamaha import send_any

# PUT – set a custom value directly:
send_any(plugin,
    value='<Main_Zone><Sound_Video><Tone><Bass>'
          '<Val>20</Val><Exp>1</Exp><Unit>dB</Unit>'
          '</Bass></Tone></Sound_Video></Main_Zone>',
    action='Put')

# GET – retrieve a value by placing GetParam in the XML:
result = send_any(plugin,
    value='<Main_Zone><Basic_Status><Volume><Lvl><Val>GetParam</Val></Lvl></Volume></Basic_Status></Main_Zone>',
    action='Get')
print result   # e.g. "-300"  (tenths of dB → -30.0 dB)
```

### Response
#### Success Response (200)
- **result** (string) - The result of the GET command, if applicable. For PUT commands, no explicit result is documented.
```

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

### Send Arbitrary YNC Commands

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Send an arbitrary YNC PUT or GET command and optionally return the result. This is useful for commands not yet implemented by the plugin.

```python
from yamaha import send_any

# PUT – set a custom value directly:
send_any(plugin,
    value='<Main_Zone><Sound_Video><Tone><Bass>'
          '<Val>20</Val><Exp>1</Exp><Unit>dB</Unit>'
          '</Bass></Tone></Sound_Video></Main_Zone>',
    action='Put')

# GET – retrieve a value by placing GetParam in the XML:
result = send_any(plugin,
    value='<Main_Zone><Basic_Status><Volume><Lvl><Val>GetParam</Val></Lvl></Volume></Basic_Status></Main_Zone>',
    action='Get')
print result   # e.g. "-300"  (tenths of dB → -30.0 dB)
```

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

### Configure Initial and Maximum Volume

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Set the maximum allowable volume using `set_max_volume` and configure the initial power-on volume with `set_init_volume`, specifying the value and mode.

```python
from yamaha import set_max_volume
set_max_volume(plugin, zone=0, value=0.0)

# Configure initial power-on volume to -40 dB, mode "On":
from yamaha import set_init_volume
set_init_volume(plugin, zone=0, value=-40.0, mode="On")
```

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

### Register Yamaha RX-V Plugin with EventGhost

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

This code snippet shows the plugin registration process for EventGhost. It defines metadata like name, author, version, and description. Configuration parameters for network connection and auto-detection are also listed.

```python
# __init__.py – plugin bootstrap (handled automatically by EventGhost)
eg.RegisterPlugin(
    name            = "Yamaha RX-V Network Receiver",
    author          = "Anthony Casagrande (BirdAPI), Jason Kloepping (Dragon470)",
    version         = "1.1",
    kind            = "external",
    canMultiLoad    = True,
    createMacrosOnAdd = False,
    url             = "http://www.eventghost.net/forum/viewtopic.php?f=9&t=3382",
    description     = "Control Yamaha RX-V network receivers."
)

# Plugin __start__ parameters (set via the Configure dialog):
# ip_address        – static IP, e.g. "192.168.1.50"
# port              – HTTP port, default 80
# ip_auto_detect    – True: scan LAN; False: use static IP
# auto_detect_model – "ANY" or a specific model, e.g. "RX-V775"
# auto_detect_timeout – seconds per probe, default 1.0
# default_timeout   – seconds for regular commands, default 3.0
```

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

### Display Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Control the front-panel display brightness and set the background wallpaper.

```APIDOC
## Set Display Brightness
DisplayDimmer(plugin, level)

### Parameters
- **plugin**: The plugin object.
- **level** (int): The display brightness level. Negative values indicate dimming (e.g., -2 for 50%).

## Set Wallpaper
wallpaper(plugin, pic)

### Parameters
- **plugin**: The plugin object.
- **pic** (string): The wallpaper picture to display. Valid options: 'Picture 1', 'Picture 2', 'Picture 3', 'Gray'.
```

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

### Control Display Brightness and Wallpaper

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Adjust the front-panel display brightness and set the background wallpaper image. Uses `DisplayDimmer` for brightness and `wallpaper` for background images.

```python
from yamaha import DisplayDimmer, wallpaper

# Set display to 50% brightness (level index * -1: 0=100%, -1=75%, -2=50%, ...):
DisplayDimmer(plugin, level=-2)

# Set background wallpaper to Picture 2:
wallpaper(plugin, pic='Picture 2')
```

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

### Input Source Selection

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Switch the active input on any zone, including cycling through a custom list.

```APIDOC
## Input Source Selection

### Description
Switch the active input on any zone, including cycling through a custom list.

### Functions
- `change_source(plugin, source, zone)`: Changes the input source for the specified zone.
- `get_source_name(plugin, zone)`: Gets the current input source name for the zone.

### Example Usage
```python
# Select HDMI1 on Main Zone:
change_source(plugin, source='HDMI1', zone=0)

# Select Tuner on Zone 2 (note: internal name is 'TUNER'):
change_source(plugin, source='TUNER', zone=2)

# --- Cycle inputs (via EventGhost action, equivalent logic) ---
my_inputs = ['HDMI1', 'HDMI2', 'AV1', 'TUNER']
current = get_source_name(plugin, izone)   # e.g. 'HDMI1'
idx = my_inputs.index(current) if current in my_inputs else -1
next_idx = (idx + 1) % len(my_inputs)
change_source(plugin, my_inputs[next_idx], izone)
print "Switched to", my_inputs[next_idx]
```
```

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

### GetInfo Action

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Query live status values from the receiver across zones and input sources. This action can retrieve various parameters like volume, input selection, frequency, tone levels, and active speakers.

```APIDOC
## GetInfo — `GetInfo` action

### Description
Query live status values from the receiver across zones and input sources.

### Method
`eg.plugins.YamahaRXV.GetInfo(parameter, zone)`

### Parameters
#### Path Parameters
- **parameter** (string) - Required - The status parameter to query (e.g., 'Volume Level', 'Input Selection', 'Frequency', 'Bass', 'Active Speakers').
- **zone** (string) - Required - The zone to query (e.g., 'Main Zone', 'Zone 2', 'Tuner', 'System').

### Request Example
```python
# Volume of Main Zone:
vol = eg.plugins.YamahaRXV.GetInfo('Volume Level', 'Main Zone')
print vol   # e.g. "-30.0 dB"

# Current input selection on Main Zone:
inp = eg.plugins.YamahaRXV.GetInfo('Input Selection', 'Main Zone')
print inp   # e.g. "HDMI1"

# Tuner frequency:
freq = eg.plugins.YamahaRXV.GetInfo('Frequency', 'Tuner')
print freq   # e.g. "101.1 MHz"

# Bass level on Zone 2:
bass = eg.plugins.YamahaRXV.GetInfo('Bass', 'Zone 2')
print bass   # e.g. "3.0 dB"

# Active speaker list (system-level):
spks = eg.plugins.YamahaRXV.GetInfo('Active Speakers', 'System')
print spks   # ['Front_R', 'Front_L', 'Center', 'Sur_R', 'Sur_L', 'Subwoofer_1']
```

### Response
#### Success Response (200)
- **value** (string or list) - The queried status value. The type depends on the parameter requested.
```

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

### Scene Selection

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Activate a stored scene (1–12) on any zone.

```APIDOC
## Scene Selection

### Description
Activate a stored scene (1–12) on any zone.

### Functions
- `set_scene(plugin, scene_num, zone)`: Activates the specified scene number for the zone.

### Example Usage
```python
# Activate Scene 3 on Main Zone:
set_scene(plugin, scene_num=3, zone=0)
```
```

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

### Assign Video Output and Audio Input

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Configure video output sources for specific features and assign audio inputs to video sources, primarily for the Main Zone. Uses `feature_video_out` and `source_audio_in`.

```python
from yamaha import feature_video_out, source_audio_in

# Route Tuner feature video output through HDMI_1:
feature_video_out(plugin, feature='TUNER', source='HDMI_1')

# Assign AV1 audio to HDMI_1 video:
source_audio_in(plugin, audio='AV1', video='HDMI_1')
```

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

### Adjust Volume in Any Zone

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Utilize `increase_volume`, `decrease_volume`, and `set_volume` for precise volume adjustments. Standard dB increments use fast relative commands, while other values use a read-then-write absolute approach.

```python
from yamaha import increase_volume, decrease_volume, set_volume

# Increase Main Zone by 0.5 dB (fastest path):
increase_volume(plugin, zone=0, inc=0.5)

# Decrease Zone 2 by 2 dB:
decrease_volume(plugin, zone=2, dec=2.0)

# Set Main Zone to exactly -30.0 dB:
set_volume(plugin, zone=0, value=-30.0)
# Sends: <Main_Zone><Volume><Lvl><Val>-300</Val><Exp>1</Exp><Unit>dB</Unit></Lvl></Volume></Main_Zone>
```

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

### Query Receiver Status with GetInfo

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Query live status values from the receiver across zones and input sources. This action can retrieve volume, input selection, tuner frequency, tone levels, and active speaker lists.

```python
# EventGhost Python script – call the action directly:
# eg.plugins.YamahaRXV.GetInfo(object, cat)

# Volume of Main Zone:
vol = eg.plugins.YamahaRXV.GetInfo('Volume Level', 'Main Zone')
print vol   # e.g. "-30.0 dB"

# Current input selection on Main Zone:
inp = eg.plugins.YamahaRXV.GetInfo('Input Selection', 'Main Zone')
print inp   # e.g. "HDMI1"

# Tuner frequency:
freq = eg.plugins.YamahaRXV.GetInfo('Frequency', 'Tuner')
print freq   # e.g. "101.1 MHz"

# Bass level on Zone 2:
bass = eg.plugins.YamahaRXV.GetInfo('Bass', 'Zone 2')
print bass   # e.g. "3.0 dB"

# Active speaker list (system-level):
spks = eg.plugins.YamahaRXV.GetInfo('Active Speakers', 'System')
print spks   # ['Front_R', 'Front_L', 'Center', 'Sur_R', 'Sur_L', 'Subwoofer_1']
```

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

### Control Sound Modes

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Switch between different sound modes like Straight, Surround Decode, and 7-Channel Stereo. Ensure the correct plugin and zone are specified.

```python
straight(plugin, zone=0)

surround_decode(plugin, zone=0)

toggle_straight_decode(plugin, zone=0)

channel7_on(plugin, zone=0)
channel7_off(plugin, zone=0)
```

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

### Control Music Enhancer

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Toggle or explicitly enable/disable the compressed-music enhancer. Check the current state using `get_enhancer` before toggling.

```python
from yamaha import toggle_enhancer, set_enhancer, get_enhancer

# Check current state then toggle:
print "Enhancer on:", get_enhancer(plugin, zone=0)
toggle_enhancer(plugin)

# Force enhancer on for Main Zone:
set_enhancer(plugin, arg='On', zone=0)
```

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

### Control Radio Tuning and Presets

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Tune the built-in radio tuner to specific frequencies (FM/AM) or navigate through stored presets. Includes functions for frequency setting, auto-seek, band toggling, and preset navigation.

```python
from yamaha import (
    set_radio_freq, radio_freq, toggle_radio_amfm,
    next_radio_preset, prev_radio_preset,
    set_radio_band, get_radio_band
)

# Tune to FM 101.1 MHz:
set_radio_freq(plugin, freq=101.1, band='FM')

# Tune to AM 1010 kHz:
set_radio_freq(plugin, freq=1010, band='AM')

# Step frequency up (auto-seek):
radio_freq(plugin, updown='Auto Up')

# Toggle between AM and FM:
toggle_radio_amfm(plugin)

# Advance to next stored preset (wraps automatically):
next_radio_preset(plugin)

# Go to previous preset:
prev_radio_preset(plugin)
```

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

### Manage Speaker Levels (Pattern 1)

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Read and write individual speaker trim levels for Pattern 1. Fetches current levels, allows modification, and applies changes. Also retrieves active speaker names.

```python
from yamaha import set_pattern1, get_system_pattern_1

# Fetch current speaker levels from the receiver:
levels = get_system_pattern_1(plugin)

# Adjust center channel +1 dB and apply:
for spk in levels:
    if spk[0] == 'Center':
        spk[1] = 1.0
set_pattern1(plugin, levels)

# Get only the names of active speakers:
active = get_system_pattern_1(plugin, param="Active Speakers")
print active
```

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

### Control Power State

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Manage the power state of any zone using `power_on`, `power_standby`, and `toggle_on_standby`. `toggle_on_standby` switches the zone between On and Standby modes.

```python
from yamaha import power_on, power_standby, toggle_on_standby

# Power on Main Zone:
power_on(plugin, zone=0)

# Put Zone 2 to standby:
power_standby(plugin, zone=2)

# Toggle Main Zone between On and Standby:
toggle_on_standby(plugin, zone=0)
# Sends: <Main_Zone><Power_Control><Power>On/Standby</Power></Power_Control></Main_Zone>
```

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

### Enhancer Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Toggle or explicitly set the compressed-music enhancer state.

```APIDOC
## Toggle Enhancer
toggle_enhancer(plugin)

## Set Enhancer State
set_enhancer(plugin, arg, zone=0)

### Parameters
- **plugin**: The plugin object.
- **arg** (string): The desired state. 'On' or 'Off'.
- **zone** (int): The zone to apply the setting to. Defaults to 0.

## Get Enhancer State
get_enhancer(plugin, zone=0)

### Parameters
- **plugin**: The plugin object.
- **zone** (int): The zone to query. Defaults to 0.

### Returns
- Boolean: True if the enhancer is on, False otherwise.
```

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

### Smart Volume

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Provides two-speed volume ramping: slow step for brief presses, fast step after a threshold.

```APIDOC
## Smart Volume

### Description
Two-speed volume ramping: slow step while button is held briefly, fast step after a threshold.

### Actions (EventGhost)
- `SmartVolumeUp` (zone, step1, step2, wait): Starts ramping up volume. Increases by `step1` for the first `wait` seconds, then by `step2`.
- `SmartVolumeFinished`: Resets the smart volume timer.

### Python Script Equivalent Logic
```python
# Simulate 5 rapid presses:
for _ in range(5):
    if plugin.smart_vol_up_start is None:
        plugin.smart_vol_up_start = datetime.datetime.now()
    diff = datetime.datetime.now() - plugin.smart_vol_up_start
    step = 0.5 if diff.seconds < 2.0 else 2.0
    increase_volume(plugin, zone=plugin.active_zone, inc=step)
    time.sleep(0.2)

# After button release:
plugin.smart_vol_up_start = None
plugin.smart_vol_down_start = None
```
```

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

### Query Receiver for Available Zones and Sources

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

This function queries the receiver for its supported zones and input sources, caching them within the plugin. It also provides a mapping for internal to display names of sources.

```python
# helpers.py
from helpers import setup_availability

setup_availability(plugin)

print plugin.AVAILABLE_ZONES
# ['Main Zone', 'Zone 2']

print plugin.AVAILABLE_SOURCES
# ['HDMI1', 'HDMI2', 'HDMI3', 'AV1', 'AV2', 'V AUX', 'Tuner', 'Spotify', 'AirPlay', ...]

print plugin.AVAILABLE_SOURCES_RENAME
# [['HDMI1', 'HDMI1'], ['AV_1', 'AV1'], ...]  – internal name → display name pairs
```

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

### Manage Input Volume Trim

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Read or write per-source volume trim levels. Values are stored as integer tenths of dB.

```python
from yamaha import get_system_io_vol_trim, set_system_io_vol_trim

# Fetch current trims:
trims = get_system_io_vol_trim(plugin)
# trims = [['TUNER', 0], ['HDMI_1', 5], ['HDMI_2', 0], ['AV_1', -10], ...]
# Values are stored as integer tenths of dB (e.g. 5 = 0.5 dB, -10 = -1.0 dB)

# Boost HDMI_1 by 1.5 dB:
for src in trims:
    if src[0] == 'HDMI_1':
        src[1] = 15   # 1.5 dB * 10
set_system_io_vol_trim(plugin, trims)
```

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

### Set Volume for Specific Zone

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Use `zone_put_xml` to send custom XML commands for volume control to a specific zone. This method wraps the XML in a Yamaha command structure.

```python
zone_put_xml(plugin, zone=2,
    xml='<Volume><Lvl><Val>-300</Val><Exp>1</Exp><Unit>dB</Unit></Lvl></Volume>')
# Wraps automatically as:
# <YAMAHA_AV cmd="PUT"><Zone_2><Volume>...</Volume></Zone_2></YAMAHA_AV>
```

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

### Power Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Control the power state for any zone.

```APIDOC
## Power Control

### Description
Control power state for any zone.

### Functions
- `power_on(plugin, zone)`: Powers the specified zone on.
- `power_standby(plugin, zone)`: Puts the specified zone into standby mode.
- `toggle_on_standby(plugin, zone)`: Toggles the specified zone between On and Standby.

### Example Usage
```python
# Power on Main Zone:
power_on(plugin, zone=0)

# Put Zone 2 to standby:
power_standby(plugin, zone=2)

# Toggle Main Zone between On and Standby:
toggle_on_standby(plugin, zone=0)
```
```

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

### Video & Audio Assignment

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Assign video output sources and audio inputs for specific video sources, primarily for the Main Zone.

```APIDOC
## Assign Video Output
feature_video_out(plugin, feature, source)

### Parameters
- **plugin**: The plugin object.
- **feature** (string): The feature to assign video output for (e.g., 'TUNER').
- **source** (string): The video output source (e.g., 'HDMI_1').

## Assign Audio Input to Video Source
source_audio_in(plugin, audio, video)

### Parameters
- **plugin**: The plugin object.
- **audio** (string): The audio input source (e.g., 'AV1').
- **video** (string): The video source to assign the audio to (e.g., 'HDMI_1').
```

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

### Verify Static IP Connection to Receiver

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

This script directly uses the VerifyStaticIP action to check if a Yamaha receiver is reachable at the configured static IP address. It prints a success or failure message.

```python
# EventGhost Python script using the action directly:
result = eg.plugins.YamahaRXV.VerifyStaticIP()
if result:
    print "Receiver online at", eg.plugins.YamahaRXV.ip_address
else:
    print "Receiver NOT found – check IP or cable"
# Returns True on success, False if unreachable or auto-detect is enabled instead.
```

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

### Active Zone Management

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Track which zone is currently 'active' so zone-agnostic actions target the correct zone. This includes setting the active zone and converting zone names to their internal integer representation.

```APIDOC
## Active Zone Management — `set_active_zone` / `convert_zone_to_int`

### Description
Track which zone is currently "active" so zone-agnostic actions target the right zone.

### Method
`set_active_zone(plugin, zone)`
`convert_zone_to_int(plugin, zone_name, convert_active=False)`

### Parameters
#### `set_active_zone`
- **plugin**: The EventGhost plugin instance.
- **zone** (integer or string) - Required - The zone to set as active (e.g., 2 for Zone 2, 'Main Zone').

#### `convert_zone_to_int`
- **plugin**: The EventGhost plugin instance.
- **zone_name** (string) - Required - The name of the zone to convert.
- **convert_active** (boolean) - Optional - If True, and `zone_name` is 'Active Zone', returns the plugin's current active zone integer.

### Request Example
```python
from yamaha import set_active_zone
from helpers import convert_zone_to_int

# Switch active zone to Zone 2:
set_active_zone(plugin, zone=2)
# Console: "Active Zone: Zone 2"

# Convert zone name strings to the internal integer representation:
convert_zone_to_int(plugin, 'Main Zone')      # → 0
convert_zone_to_int(plugin, 'Zone 2')         # → 2
convert_zone_to_int(plugin, 'Active Zone')    # → -1  (resolved later)
convert_zone_to_int(plugin, 'Active Zone', convert_active=True)  # → plugin.active_zone
convert_zone_to_int(plugin, 'Zone A')         # → -65 (negative ASCII of 'A')
```

### Response
#### Success Response (`set_active_zone`)
No explicit return value documented, operation is performed.

#### Success Response (`convert_zone_to_int`)
- **zone_integer** (integer) - The internal integer representation of the zone name.
```

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

### Set Sleep Timer

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Configure a sleep timer for any zone, with options to turn it off or set durations like 30, 60, 90, or 120 minutes. Uses the `set_sleep` function.

```python
from yamaha import set_sleep

# Set Main Zone to sleep after 30 minutes:
set_sleep(plugin, arg='30 min', zone=0)

# Cancel sleep timer:
set_sleep(plugin, arg='Off', zone=0)
```

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

### Surround Mode

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Switch between Straight, Surround Decode, and 7-Channel Stereo modes.

```APIDOC
## Surround Mode

### Description
Switch between Straight, Surround Decode, and 7-Channel Stereo modes.

### Functions
- `straight(plugin, zone)`: Sets the surround mode to Straight.
- `surround_decode(plugin, zone)`: Sets the surround mode to Surround Decode.
- `toggle_straight_decode(plugin, zone)`: Toggles between Straight and Surround Decode modes.
- `channel7_on(plugin, zone)`: Enables 7-Channel Stereo mode.
- `channel7_off(plugin, zone)`: Disables 7-Channel Stereo mode.

### Example Usage
```python
# Set Main Zone to Straight mode:
straight(plugin, zone=0)

# Set Zone 2 to Surround Decode:
surround_decode(plugin, zone=2)

# Toggle Main Zone between Straight and Surround Decode:
toggle_straight_decode(plugin, zone=0)

# Enable 7-Channel Stereo on Zone 2:
channel7_on(plugin, zone=2)

# Disable 7-Channel Stereo on Main Zone:
channel7_off(plugin, zone=0)
```
```

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

### Control Surround Sound Modes

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Switch between Straight, Surround Decode, and 7-Channel Stereo modes using functions like `straight`, `surround_decode`, `toggle_straight_decode`, `channel7_on`, and `channel7_off`.

```python
from yamaha import straight, surround_decode, toggle_straight_decode, channel7_on, channel7_off
```

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

### Activate Stored Scene

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Activate a stored scene (1–12) on any zone using the `set_scene` function, specifying the scene number and the target zone.

```python
from yamaha import set_scene

# Activate Scene 3 on Main Zone:
set_scene(plugin, scene_num=3, zone=0)
# Sends: <Main_Zone><Scene><Scene_Sel>Scene 3</Scene_Sel></Scene></Main_Zone>
```

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

### Volume Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Adjust or set the playback volume on any zone. Supports standard dB increments for speed and falls back to absolute values.

```APIDOC
## Volume Control

### Description
Adjust or set the playback volume on any zone. Standard dB increments (0.5, 1, 2, 5 dB) use the receiver's built-in relative commands for speed; all other values fall back to a read-then-write absolute approach.

### Functions
- `increase_volume(plugin, zone, inc)`: Increases the volume by the specified increment.
- `decrease_volume(plugin, zone, dec)`: Decreases the volume by the specified decrement.
- `set_volume(plugin, zone, value)`: Sets the volume to an absolute value.
- `set_max_volume(plugin, zone, value)`: Sets the maximum allowable volume.
- `set_init_volume(plugin, zone, value, mode)`: Configures the initial power-on volume.

### Example Usage
```python
# Increase Main Zone by 0.5 dB (fastest path):
increase_volume(plugin, zone=0, inc=0.5)

# Decrease Zone 2 by 2 dB:
decrease_volume(plugin, zone=2, dec=2.0)

# Set Main Zone to exactly -30.0 dB:
set_volume(plugin, zone=0, value=-30.0)

# Set max allowable volume to 0 dB (zone 0):
set_max_volume(plugin, zone=0, value=0.0)

# Configure initial power-on volume to -40 dB, mode "On":
set_init_volume(plugin, zone=0, value=-40.0, mode="On")
```
```

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

### Input Volume Trim

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Read or write per-source volume trim levels, ranging from –6.0 dB to +6.0 dB. Values are stored as integer tenths of dB.

```APIDOC
## Input Volume Trim — `get_system_io_vol_trim` / `set_system_io_vol_trim`

### Description
Read or write per-source volume trim levels (–6.0 dB to +6.0 dB).

### Method
`get_system_io_vol_trim(plugin)`
`set_system_io_vol_trim(plugin, trims)`

### Parameters
#### `get_system_io_vol_trim`
- **plugin**: The EventGhost plugin instance.

#### `set_system_io_vol_trim`
- **plugin**: The EventGhost plugin instance.
- **trims**: A list of lists, where each inner list contains a source name (string) and its trim level (integer tenths of dB).

### Request Example
```python
from yamaha import get_system_io_vol_trim, set_system_io_vol_trim

# Fetch current trims:
trims = get_system_io_vol_trim(plugin)
# trims = [['TUNER', 0], ['HDMI_1', 5], ['HDMI_2', 0], ['AV_1', -10], ...]

# Boost HDMI_1 by 1.5 dB:
for src in trims:
    if src[0] == 'HDMI_1':
        src[1] = 15   # 1.5 dB * 10
set_system_io_vol_trim(plugin, trims)
```

### Response
#### Success Response (`get_system_io_vol_trim`)
- **trims** (list of lists): A list where each inner list contains a source name (string) and its current trim level (integer tenths of dB).

#### Success Response (`set_system_io_vol_trim`)
No explicit return value documented, operation is performed.
```

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

### Send Remote Control Codes

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Send IR-equivalent remote control commands for navigation, playback, and numeric input using raw hex codes. Requires importing `send_code` and `globals`.

```python
from yamaha import send_code
import globals

# Send a cursor Up command to Main Zone using the raw hex code:
send_code(plugin, code=globals.CURSOR_CODES[1]['Up'])

# Send Play to Zone 2:
send_code(plugin, code=globals.OPERATION_CODES[2]['Play'])

# Send digit '5' to Main Zone:
send_code(plugin, code=globals.NUMCHAR_CODES[1]['5'])
```

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

### Manage Active Zone

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Track which zone is currently "active" so zone-agnostic actions target the right zone. Also provides utility to convert zone names to their internal integer representation.

```python
from yamaha import set_active_zone
from helpers import convert_zone_to_int

# Switch active zone to Zone 2:
set_active_zone(plugin, zone=2)
# Console: "Active Zone: Zone 2"

# Convert zone name strings to the internal integer representation:
convert_zone_to_int(plugin, 'Main Zone')      # → 0
convert_zone_to_int(plugin, 'Zone 2')         # → 2
convert_zone_to_int(plugin, 'Active Zone')    # → -1  (resolved later)
convert_zone_to_int(plugin, 'Active Zone', convert_active=True)  # → plugin.active_zone
convert_zone_to_int(plugin, 'Zone A')         # → -65 (negative ASCII of 'A')
```

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

### Cursor & Remote Actions

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Send IR-equivalent remote control codes for navigation, playback, and numeric input across different zones.

```APIDOC
## Send Remote Code
send_code(plugin, code)

### Parameters
- **plugin**: The plugin object.
- **code** (string): The raw hex code for the remote control action.

### Available Actions
- **Cursor Actions**: Up, Down, Left, Right, Enter, Return, Level, On Screen, Option, Top Menu, Pop Up Menu.
- **Operation Actions**: Play, Stop, Pause, Search-, Search+, Skip-, Skip+, FM, AM.
- **Numchar Actions**: 0-9, +10, ENT.
```

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

### Sound Modes

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Control various sound modes including Straight, Surround Decode, 7-Channel Stereo, and their toggles.

```APIDOC
## Enable Straight mode
straight(plugin, zone=0)

## Switch to Surround Decode
surround_decode(plugin, zone=0)

## Toggle between Straight and Surround Decode
toggle_straight_decode(plugin, zone=0)

## Enable 7-Channel Stereo
channel7_on(plugin, zone=0)

## Return to Standard
channel7_off(plugin, zone=0)
```

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

### XML Utility

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Auto-close unclosed XML tags in a partial XML string. This is a helper function for constructing valid XML commands.

```APIDOC
## XML Utility — `close_xml_tags`

### Description
Auto-close unclosed XML tags in a partial XML string.

### Method
`close_xml_tags(xml_string)`

### Parameters
#### Path Parameters
- **xml_string** (string) - Required - The partial XML string that may contain unclosed tags.

### Request Example
```python
from helpers import close_xml_tags

partial = '<YAMAHA_AV cmd="PUT"><Main_Zone><Power_Control><Power>On'
complete = close_xml_tags(partial)
print complete
# <YAMAHA_AV cmd="PUT"><Main_Zone><Power_Control><Power>On</Power></Power_Control></Main_Zone></YAMAHA_AV>
```

### Response
#### Success Response (200)
- **complete_xml** (string) - The XML string with all tags properly closed.
```

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

### Auto-Detect Yamaha Receiver IP Address

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

This function scans the local subnet in parallel threads to find a Yamaha receiver. It stores the first responding IP address and model name. After detection, it populates available zones and sources.

```python
# helpers.py
# Called automatically on plugin start, or manually via the AutoDetectIP action.

from helpers import auto_detect_ip_threaded, setup_availability

# Inside an eg.ActionBase or script:
ip = auto_detect_ip_threaded(plugin)
# Console output:
#   Searching for Yamaha Recievers (ANY)...
#   192.168.1.55: RX-V775
#   Found Yamaha Receiver IP: 192.168.1.55 [RX-V775]

if ip is not None:
    setup_availability(plugin)   # populate AVAILABLE_ZONES / AVAILABLE_SOURCES
    print plugin.AVAILABLE_ZONES    # e.g. ['Main Zone', 'Zone 2']
    print plugin.AVAILABLE_SOURCES  # e.g. ['HDMI1', 'HDMI2', 'AV1', 'Tuner', ...]
```

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

### Toggle or Set Mute State

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Control the mute state of any zone using `toggle_mute`, `mute_on`, `mute_off`, and `get_mute`. `get_mute` returns a boolean indicating the current mute status.

```python
from yamaha import toggle_mute, mute_on, mute_off, get_mute

# Toggle current mute state on Main Zone:
toggle_mute(plugin, zone=0)

# Force mute on:
mute_on(plugin, zone=0)

# Check current mute state:
is_muted = get_mute(plugin, zone=0)   # Returns True / False
print "Muted:", is_muted
```

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

### Adjust Bass and Treble

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Modify bass and treble levels for any zone within a range of -6.0 dB to +6.0 dB. Imports `set_bass` and `set_treble` from the `yamaha` library.

```python
from yamaha import set_bass, set_treble

# Boost bass by 3 dB on Main Zone:
set_bass(plugin, zone=0, value=3.0)

# Cut treble by 2 dB on Main Zone:
set_treble(plugin, zone=0, value=-2.0)
```

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

### Mute Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Toggle or explicitly set the mute state on any zone.

```APIDOC
## Mute Control

### Description
Toggle or explicitly set mute state on any zone.

### Functions
- `toggle_mute(plugin, zone)`: Toggles the current mute state.
- `mute_on(plugin, zone)`: Forces mute to be on.
- `mute_off(plugin, zone)`: Forces mute to be off.
- `get_mute(plugin, zone)`: Returns `True` if muted, `False` otherwise.

### Example Usage
```python
# Toggle current mute state on Main Zone:
toggle_mute(plugin, zone=0)

# Force mute on:
mute_on(plugin, zone=0)

# Check current mute state:
is_muted = get_mute(plugin, zone=0)
print "Muted:", is_muted
```
```

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

### Tone Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Adjust bass and treble levels for any zone. Values range from -6.0 dB to +6.0 dB.

```APIDOC
## Set Bass Level
set_bass(plugin, zone, value)

### Parameters
- **plugin**: The plugin object.
- **zone** (int): The zone to adjust. Defaults to 0.
- **value** (float): The bass level in dB (-6.0 to 6.0).

## Set Treble Level
set_treble(plugin, zone, value)

### Parameters
- **plugin**: The plugin object.
- **zone** (int): The zone to adjust. Defaults to 0.
- **value** (float): The treble level in dB (-6.0 to 6.0).
```

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

### Auto-close XML Tags

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Auto-close unclosed XML tags in a partial XML string. This is useful for constructing valid XML commands.

```python
from helpers import close_xml_tags

partial = '<YAMAHA_AV cmd="PUT"><Main_Zone><Power_Control><Power>On'
complete = close_xml_tags(partial)
print complete
# <YAMAHA_AV cmd="PUT"><Main_Zone><Power_Control><Power>On</Power></Power_Control></Main_Zone></YAMAHA_AV>
```

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

### Speaker Levels

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Read or write individual speaker trim levels for Pattern 1. Allows fine-tuning of audio output for each speaker.

```APIDOC
## Get Speaker Levels (Pattern 1)
get_system_pattern_1(plugin, param="Speaker Levels")

### Parameters
- **plugin**: The plugin object.
- **param** (string): Specifies to retrieve 'Speaker Levels' or 'Active Speakers'. Defaults to 'Speaker Levels'.

### Returns
- List of lists, where each inner list contains speaker name and its level, or a list of active speaker names.

## Set Speaker Levels (Pattern 1)
set_pattern1(plugin, levels)

### Parameters
- **plugin**: The plugin object.
- **levels** (list): A list of lists, where each inner list contains speaker name and its level to apply.
```

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

### Sleep Timer

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Set or cancel a sleep timer for any zone. Supports predefined intervals and an 'Off' state.

```APIDOC
## Set Sleep Timer
set_sleep(plugin, arg, zone=0)

### Parameters
- **plugin**: The plugin object.
- **arg** (string): The sleep timer duration. Valid values: 'Off', '30 min', '60 min', '90 min', '120 min', 'Last'.
- **zone** (int): The zone to set the timer for. Defaults to 0.
```

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

### Radio Control

Source: https://context7.com/ajcasagrande/yamaha-network-receivers/llms.txt

Tune the built-in radio tuner to specific frequencies, toggle bands, navigate presets, and control auto-seek.

```APIDOC
## Set Radio Frequency
set_radio_freq(plugin, freq, band)

### Parameters
- **plugin**: The plugin object.
- **freq** (float): The frequency to tune to (e.g., 101.1 for FM, 1010 for AM).
- **band** (string): The radio band ('FM' or 'AM').

## Step Radio Frequency
radio_freq(plugin, updown)

### Parameters
- **plugin**: The plugin object.
- **updown** (string): Direction to step. Accepts 'Auto Up', 'Auto Down', 'Up', 'Down'.

## Toggle Radio Band
toggle_radio_amfm(plugin)

## Advance to Next Preset
next_radio_preset(plugin)

## Go to Previous Preset
prev_radio_preset(plugin)

## Set Radio Band
set_radio_band(plugin, band)

### Parameters
- **plugin**: The plugin object.
- **band** (string): The radio band to set ('FM' or 'AM').

## Get Radio Band
get_radio_band(plugin)

### Returns
- String: The current radio band ('FM' or 'AM').
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.