### Get Available Players and Microphones

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves lists of configured player profiles and connected microphones.

```APIDOC
## Available Players and Microphones

### Description
Retrieve lists of configured player profiles and connected microphones.

### Endpoints

#### Get available player profiles

##### Method
GET

##### Endpoint
/api/rest/availablePlayers

#### Get available microphones

##### Method
GET

##### Endpoint
/api/rest/availableMicrophones

### Request Example (Available Players)
```bash
curl -X GET "http://localhost:6789/api/rest/availablePlayers"
```

### Request Example (Available Microphones)
```bash
curl -X GET "http://localhost:6789/api/rest/availableMicrophones"
```

### Response
#### Success Response (200)
(The exact structure of these responses is not detailed in the provided text, but they would typically return arrays of strings or objects representing players and microphones.)

#### Response Example
(Example response structures are not provided in the source text.)
```

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

### Get All Songs

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves a list of all loaded songs with their metadata, including artist, title, and unique identifier.

```APIDOC
## GET /api/rest/songs

### Description
Retrieves the list of all loaded songs with their metadata including artist, title, and unique identifier.

### Method
GET

### Endpoint
/api/rest/songs

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:6789/api/rest/songs"
```

### Response
#### Success Response (200)
- **IsSongScanFinished** (boolean) - Indicates if the song scan process is complete.
- **SongCount** (integer) - The total number of songs found.
- **SongList** (array) - A list of song objects.
  - **Artist** (string) - The artist of the song.
  - **Title** (string) - The title of the song.
  - **Hash** (string) - A unique identifier for the song.

#### Response Example
```json
{
  "IsSongScanFinished": true,
  "SongCount": 42,
  "SongList": [
    {
      "Artist": "Queen",
      "Title": "Bohemian Rhapsody",
      "Hash": "abc123def456"
    },
    {
      "Artist": "ABBA",
      "Title": "Dancing Queen",
      "Hash": "xyz789ghi012"
    }
  ]
}
```
```

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

### Get Song Details

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves detailed information about a specific song, including lyrics for each voice part.

```APIDOC
## GET /api/rest/song/{id}

### Description
Retrieves detailed information about a specific song including lyrics for each voice part.

### Method
GET

### Endpoint
/api/rest/song/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the song.

### Request Example
```bash
curl -X GET "http://localhost:6789/api/rest/song/abc123def456"
```

### Response
#### Success Response (200)
- **SongId** (string) - The unique identifier of the song.
- **IsFavorite** (boolean) - Indicates if the song is marked as a favorite.
- **VoiceDisplayNameToLyricsMap** (object) - A map where keys are voice display names and values are the corresponding lyrics.

#### Response Example
```json
{
  "SongId": "abc123def456",
  "IsFavorite": true,
  "VoiceDisplayNameToLyricsMap": {
    "Player 1": "Is this the real life? Is this just fantasy?",
    "Player 2": "Caught in a landslide, no escape from reality"
  }
}
```
```

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

### Get Available Players and Microphones - REST API

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Fetches lists of configured player profiles and connected microphones available to the UltraStar Play application. This information is necessary for setting up gameplay sessions and assigning inputs. Separate endpoints exist for retrieving player profiles and microphone lists.

```bash
# Get available player profiles
curl -X GET "http://localhost:6789/api/rest/availablePlayers"

# Get available microphones
curl -X GET "http://localhost:6789/api/rest/availableMicrophones"
```

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

### Get Song Cover Image

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves the cover image or fallback background image for a song, encoded as base64 JPEG.

```APIDOC
## GET /api/rest/song/{id}/image

### Description
Retrieves the cover image (or background image as fallback) for a song as base64-encoded JPEG.

### Method
GET

### Endpoint
/api/rest/song/{id}/image

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the song.

### Request Example
```bash
curl -X GET "http://localhost:6789/api/rest/song/abc123def456/image"
```

### Response
#### Success Response (200)
- **JpgBytesBase64** (string) - The song's cover image encoded in base64 as a JPEG.

#### Response Example
```json
{
  "JpgBytesBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}
```
```

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

### Get Song Details - REST API

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Fetches detailed information for a specific song, including lyrics for each voice part. This is essential for displaying song content to players and preparing for gameplay. The request requires a song ID, and the response includes the song ID, favorite status, and a map of voice display names to lyrics.

```bash
# Get song details by ID
curl -X GET "http://localhost:6789/api/rest/song/abc123def456"

# Response
{
  "SongId": "abc123def456",
  "IsFavorite": true,
  "VoiceDisplayNameToLyricsMap": {
    "Player 1": "Is this the real life? Is this just fantasy?",
    "Player 2": "Caught in a landslide, no escape from reality"
  }
}
```

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

### Song Queue Management - REST API

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Provides endpoints for managing the song queue, allowing users to add, update, and delete songs from the upcoming performance list. This is crucial for interactive gameplay and managing the flow of the karaoke session. Operations include GET for the current queue, POST to add or update entries, and DELETE to remove them.

```bash
# Get current song queue
curl -X GET "http://localhost:6789/api/rest/songQueue"

# Add song to queue
curl -X POST "http://localhost:6789/api/rest/songQueue/entry" \
  -H "Content-Type: application/json" \
  -d '{
    "SongId": "abc123def456",
    "PlayerNames": ["Player1", "Player2"],
    "MicProfileNames": ["USB Microphone", "Companion App"]
  }'

# Update song queue entry at index 0
curl -X POST "http://localhost:6789/api/rest/songQueue/entry/0" \
  -H "Content-Type: application/json" \
  -d '{
    "SongId": "abc123def456",
    "PlayerNames": ["Player1"],
    "MicProfileNames": ["USB Microphone"]
  }'

# Delete song queue entry at index 0
curl -X DELETE "http://localhost:6789/api/rest/songQueue/entry/0"
```

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

### Get Statistics

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves player statistics, including high scores and play counts.

```APIDOC
## GET /api/rest/stats

### Description
Retrieve player statistics including high scores and play counts.

### Method
GET

### Endpoint
/api/rest/stats

### Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:6789/api/rest/stats"
```

### Response
#### Success Response (200)
(The exact structure of the statistics response is not detailed in the provided text, but it would typically include player performance data.)

#### Response Example
(Example response structure is not provided in the source text.)
```

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

### Configure UI Shadow and Static Background

Source: https://github.com/dorphalsig/usdx-play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt

Sets UI shadow properties like opacity and offset, and configures a static background image with its path and scaling mode.

```json
{
    "uiShadowOpacity": 0.33,
    "uiShadowOffset": { "x": -16, "y": 10 },
    "staticBackground": {
        "imagePath": "backgrounds/open-sign-1836961_1920.jpg",
        "imageScaleMode": "ScaleAndCrop"
    }
}
```

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

### Configure Video Preview Color

Source: https://github.com/dorphalsig/usdx-play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt

Sets the color for the video preview in the song select screen. Can also be used to make the preview transparent.

```json
{
    "videoPreviewColor": "#00FF0022"
}
```

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

### Define Microphone Colors

Source: https://github.com/dorphalsig/usdx-play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt

Lists the available colors that can be assigned to recording devices.

```json
{
    "microphoneColors": [
        "#FF0000",
        "#00FF00",
        "#0000FF"
    ]
}
```

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

### Configure Custom Song Rating Icons

Source: https://github.com/dorphalsig/usdx-play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt

Specifies custom image paths for song rating emojis, from 'toneDeaf' to 'ultrastar'. If not provided, default icons are used.

```json
{
    "songRatingIcons": {
        "toneDeaf": "icons/theme name/rating_0.png",
        "amateur": "icons/theme name/rating_1.png",
        "wannabe": "icons/theme name/rating_2.png",
        "hopeful": "icons/theme name/rating_3.png",
        "risingStar": "icons/theme name/rating_4.png",
        "leadSinger": "icons/theme name/rating_5.png",
        "superstar": "icons/theme name/rating_6.png",
        "ultrastar": "icons/theme name/rating_7.png"
    }
}
```

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

### Get Statistics - REST API

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves player statistics, such as high scores and play counts, from the UltraStar Play application. This endpoint is valuable for tracking player progress and game performance. It returns a JSON object containing various statistical data.

```bash
# Get all statistics
curl -X GET "http://localhost:6789/api/rest/stats"
```

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

### Basic Unity MonoBehaviour with UniInject and UniRx (C#)

Source: https://github.com/dorphalsig/usdx-play/blob/master/UltraStar Play/Assets/ScriptTemplates/81-C

This C# script is a fundamental Unity MonoBehaviour component. It implements INeedInjection from UniInject, indicating that its dependencies will be injected. It also includes placeholders for Start and Update methods, common in Unity game development, and uses UniRx for reactive extensions.

```csharp
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;
using UnityEngine.UIElements;
using UniInject;
using UniRx;

// Disable warning about fields that are never assigned, their values are injected.
#pragma warning disable CS0649

public class #SCRIPTNAME# : MonoBehaviour, INeedInjection
{
	private void Start() {
	
	}
	
	private void Update() {
	
	}
}
```

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

### Input Simulation

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Simulates keyboard and mouse input for remote control of the application.

```APIDOC
## Input Simulation

### Description
Simulate keyboard and mouse input for remote control of the application.

### Endpoints

#### Keyboard Navigation

##### Method
POST

##### Endpoints
- `/api/rest/input/leftArrowKey`
- `/api/rest/input/rightArrowKey`
- `/api/rest/input/upArrowKey`
- `/api/rest/input/downArrowKey`
- `/api/rest/input/enterKey`
- `/api/rest/input/escapeKey`
- `/api/rest/input/spaceKey`

#### Volume Control

##### Method
POST

##### Endpoints
- `/api/rest/input/volumeUpKey`
- `/api/rest/input/volumeDownKey`

#### Mouse Operations

##### Method
POST

##### Endpoints
- `/api/rest/input/leftMouseButton`
- `/api/rest/input/mouseDelta/{deltaX}/{deltaY}`
- `/api/rest/input/scrollWheel/{deltaX}/{deltaY}`

### Request Example (Keyboard)
```bash
curl -X POST "http://localhost:6789/api/rest/input/leftArrowKey"
```

### Request Example (Mouse Delta)
```bash
curl -X POST "http://localhost:6789/api/rest/input/mouseDelta/100/-50"
```
```

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

### Define Scene-Specific Backgrounds

Source: https://github.com/dorphalsig/usdx-play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt

Allows overwriting default background settings for specific scenes, supporting both static and dynamic background configurations.

```json
{
    "sceneSpecificBackgrounds": {
        "MainScene": {
            "staticBackground": { ... },
            "dynamicBackground": { ... }
        }
    }
}
```

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

### UniInject Component Injection (C#)

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Demonstrates how to use UniInject attributes like [Inject] and [InjectedInInspector] to inject dependencies into a MonoBehaviour component. It also shows the IInjectionFinishedListener interface for post-injection logic. Dependencies can be singletons, UI elements by UXML name, or inspector-assigned fields.

```csharp
public class MyComponent : MonoBehaviour, INeedInjection, IInjectionFinishedListener
{
    // Inject singleton managers
    [Inject]
    private SongMetaManager songMetaManager;

    [Inject]
    private Settings settings;

    // Inject UI elements by UXML name
    [Inject(UxmlName = R.UxmlNames.playButton)]
    private Button playButton;

    // Inject from inspector
    [InjectedInInspector]
    public AudioSource audioSource;

    // Called after all injections complete
    public void OnInjectionFinished()
    {
        // Safe to use injected dependencies here
        playButton.clicked += OnPlayClicked;
    }

    private void OnPlayClicked()
    {
        var songs = songMetaManager.GetSongMetas();
        Debug.Log($"Playing from {songs.Count} available songs");
    }
}
```

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

### Get Song Cover Image - REST API

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves the cover image or background image for a given song, encoded as a base64 JPEG. This endpoint is used to display visual media associated with a song. The request requires a song ID, and the response contains the base64 encoded image data.

```bash
# Get song cover image
curl -X GET "http://localhost:6789/api/rest/song/abc123def456/image"

# Response
{
  "JpgBytesBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}
```

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

### UniInject Custom Child Injector Creation (C#)

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Illustrates how to create a child injector from an existing injector and configure it with custom bindings. This allows for scoped dependency injection, such as providing a specific instance for a binding. The Inject method is then used to perform injection on a target object.

```csharp
Injector childInjector = injector.CreateChildInjector()
    .WithBindingForInstance(customObject);
childInjector.Inject(targetObject);
```

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

### Get All Songs - REST API

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Retrieves a list of all loaded songs and their metadata from the UltraStar Play application. This endpoint is useful for displaying available songs to the user or for external applications to query song information. It returns a JSON object containing song count and a list of songs with artist, title, and hash.

```bash
# Get all loaded songs
curl -X GET "http://localhost:6789/api/rest/songs"

# Response
{
  "IsSongScanFinished": true,
  "SongCount": 42,
  "SongList": [
    {
      "Artist": "Queen",
      "Title": "Bohemian Rhapsody",
      "Hash": "abc123def456"
    },
    {
      "Artist": "ABBA",
      "Title": "Dancing Queen",
      "Hash": "xyz789ghi012"
    }
  ]
}
```

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

### Song Queue Management

Source: https://context7.com/dorphalsig/usdx-play/llms.txt

Manage the song queue for upcoming performances, supporting add, update, and delete operations.

```APIDOC
## Song Queue Management

### Description
Manage the song queue for upcoming performances with add, update, and delete operations.

### Endpoints

#### Get current song queue

##### Method
GET

##### Endpoint
/api/rest/songQueue

#### Add song to queue

##### Method
POST

##### Endpoint
/api/rest/songQueue/entry

##### Request Body
- **SongId** (string) - Required - The unique identifier of the song to add.
- **PlayerNames** (array of strings) - Optional - Names of the players.
- **MicProfileNames** (array of strings) - Optional - Names of the microphone profiles to use.

##### Request Example
```json
{
  "SongId": "abc123def456",
  "PlayerNames": ["Player1", "Player2"],
  "MicProfileNames": ["USB Microphone", "Companion App"]
}
```

#### Update song queue entry

##### Method
POST

##### Endpoint
/api/rest/songQueue/entry/{index}

##### Parameters
#### Path Parameters
- **index** (integer) - Required - The index of the queue entry to update.

##### Request Body
- **SongId** (string) - Required - The unique identifier of the song.
- **PlayerNames** (array of strings) - Optional - Names of the players.
- **MicProfileNames** (array of strings) - Optional - Names of the microphone profiles to use.

##### Request Example
```json
{
  "SongId": "abc123def456",
  "PlayerNames": ["Player1"],
  "MicProfileNames": ["USB Microphone"]
}
```

#### Delete song queue entry

##### Method
DELETE

##### Endpoint
/api/rest/songQueue/entry/{index}

##### Parameters
#### Path Parameters
- **index** (integer) - Required - The index of the queue entry to delete.

### Request Example (Delete)
```bash
curl -X DELETE "http://localhost:6789/api/rest/songQueue/entry/0"
```
```