# Play Music

## Description

```javascript
'play music <music_id> [with [properties]]'
```

The `play music` action let's you, as it name says, play some background music for your game. You can play as many songs as you want simultaneously.

To stop the music, check out the [Stop Music documentation](/documentation/2.1.0/script-actions/stop-music.md).

**Action ID**: `Music`

**Reversible**: Yes

**Requires User Interaction**: No

## Parameters

| Name       | Type     | Description                                                                       |
| ---------- | -------- | --------------------------------------------------------------------------------- |
| music\_id  | `string` | The name of the music you want to play. These assets must be declared beforehand. |
| properties | `string` | Optional. A list of comma separated properties with their respective value.       |

### Properties

The following is a comprehensive list of the properties available for you to modify certain behaviors of the play music action.

| Property Name | Type     | Description                                                                                                                                                                                            |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| fade          | `string` | <p>The fade property let's you add a fade in effect to the music, it accepts a time in seconds, representing how much time you want it to take until the music reaches it's maximum volume.</p><p></p> |
| volume        | `number` | The volume property let's you define how high the music will be played.                                                                                                                                |
| loop          | `none`   | Make the music loop. This property does not require any value.                                                                                                                                         |

## Assets Declarations

To play a song, you must first add the file to your **`assets/music/`** directory and then declare it. To do so, Monogatari has an  has a function that will let you declare all kinds of assets for your game.

```javascript
monogatari.assets ('music', {
    '<music_id>': 'musicFileName'
});
```

### Supported Formats

Each browser has it's own format compatibility. **MP3** however is the format supported by every browser.&#x20;

If you wish to use other formats, you can check a [compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility) to discover what browsers will be able to play it.

## Examples

### Play Music

The following will play the song, and once the song ends, it will simply stop.

{% tabs %}
{% tab title="Script" %}

```javascript
monogatari.script ({
    'Start': [
        'play music mainTheme'
        'end'
    ]
});
```

{% endtab %}

{% tab title="Music Assets" %}

```javascript
monogatari.assets ('music', {
    'mainTheme': 'mainThemeSong.mp3'
});
```

{% endtab %}
{% endtabs %}

### Loop Music

The following will play the song, and once the song ends, it will start over on an infinite loop until it is stopped using the [Stop Music Action](/documentation/2.1.0/script-actions/stop-music.md).

{% tabs %}
{% tab title="Script" %}

```javascript
monogatari.script ({
    'Start': [
        'play music mainTheme with loop'
        'end'
    ]
});
```

{% endtab %}

{% tab title="Music Assets" %}

```javascript
monogatari.assets ('music', {
    'mainTheme': 'mainThemeSong.mp3'
});
```

{% endtab %}
{% endtabs %}

### Fade In effect

The following will play the song, and will use a fade in effect.

{% tabs %}
{% tab title="Script" %}

```javascript
monogatari.script ({
    'Start': [
        'play music mainTheme with fade 3'
        'end'
    ]
});
```

{% endtab %}

{% tab title="Music Assets" %}

```javascript
monogatari.assets ('music', {
    'mainTheme': 'mainThemeSong.mp3'
});
```

{% endtab %}
{% endtabs %}

### Custom Volume

The following will set the volume of this song to 73%.&#x20;

{% tabs %}
{% tab title="Script" %}

```javascript
monogatari.script ({
    'Start': [
        'play music mainTheme with volume 73'
        'end'
    ]
});
```

{% endtab %}

{% tab title="Music Assets" %}

```javascript
monogatari.assets ('music', {
    'mainTheme': 'mainThemeSong.mp3'
});
```

{% endtab %}
{% endtabs %}

Please note however, that the user's preferences regarding volumes are always respected, which means that this percentage is taken from the current player preferences, meaning that if the player has set the volume to 50%, the actual volume value for the song will be the result of:

$$
50 \* 0.73 = 36.5%
$$

### All Together

Of course, you can combine all of this properties, and remember the order doesn't really matter, you can write the properties on the order that feels more natural to you.

{% tabs %}
{% tab title="Script" %}

```javascript
monogatari.script ({
    'Start': [
        'play music mainTheme with volume 100 loop fade 20'
        'end'
    ]
});
```

{% endtab %}

{% tab title="Music Assets" %}

```javascript
monogatari.assets ('music', {
    'mainTheme': 'mainThemeSong.mp3'
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.monogatari.io/documentation/2.1.0/script-actions/play-music.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.