# Connection

### Creating a connection

A connection can easily be created by using the Connection class. The Connection class works different than the [Player](https://zyno-studio.gitbook.io/discord-audio/classes/broken-reference) and the [AudioManager](https://zyno-studio.gitbook.io/discord-audio/classes/broken-reference) class. The Connection class will make the bot join the voice channel immediately when the Connection class is being called. The Player and AudioManager classes make you join a voice channel when you start playing a song.

The Connection class requires the `channel` parameter and has an optional `options` parameter. The `channel` parameter is the voice channel that the bot needs to join. The `options` parameter has the following options:

* selfDeaf: If the bot should deaf itself. **(default is `true`)**
* selfMute: If the bot should mute itself. **(default is `false`)**

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
```

### Play a stream

You can play a stream by using the play function and returns a Promise. The function requires the `stream` parameter and has an optional `options` parameter. The stream parameter is the `stream` that you want to play. The `options` parameter has the following options:

* noListeners: If there are no members listening in the voice channel.
  * play: Continues playing the stream. **(default and recommended)**
  * pause: Pauses the stream until someone joins again.
  * stop: Stops the player and leaves the voice channel.
* volume: The volume of the stream. Max 1, min 0.
* audiotype: The audio type of the stream.
  * 'arbitrary': For mp3 audio **(default)**
  * 'ogg/opus': For ogg audio
  * 'webm/opus': For webm audio
  * 'opus': For opus audio
  * 'raw': For raw audio

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});

connection.play(`https://somecoolsite.com/somecoolstream.mp3`, {
    noListeners: 'play',
    volume: 1,
    audiotype: 'arbitrary'
}).then(stream => console.log(`Playing ${stream}`)).catch(console.log);
```

### Subscribe to a broadcast

You can subscribe to a [Broadcast](https://zyno-studio.gitbook.io/discord-audio/classes/broken-reference) by using the subscribe function. A Broadcast makes you able to create one source and play it in multiple guilds. The subscribe function only requires the `broadcast` parameter which is the Broadcast itself which you can create with the Broadcast class. The function returns a Promise which will be fullfilled if the connection successfully subscribed to the broadcast.

```javascript
const {Connection, Broadcast} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});

const broadcast = new Broadcast(`https://somecoolsite.com/somecoolstream.mp3`, {
    noListeners: 'play',
    volume: 1,
    audiotype: 'arbitrary'
});

connection.subscribe(broadcast).then(() => console.log(`Playing the broadcast!`).catch(console.log);
```

### Unsubscribe to a broadcast

You can easily unsubscribe by using the unsubscribe function.

```javascript
const {Connection, Broadcast} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
...
connection.unsubcribe();
```

### Changing the volume

You can change the volume by using the volume function. It requires the `volume` parameter which will be the volume of the stream that's playing. The volume must be at least 0 and may not be higher than 1.

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
...
connection.volume(1);
```

{% hint style="danger" %}
**This function does not work for broadcasts!** Broadcasts have their [own volume](https://zyno-studio.gitbook.io/discord-audio/classes/broken-reference) function.
{% endhint %}

### Disconnect from a connection

You can disconnect from a connection by using the disconnect function.

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
...
connection.disconnect();
```

{% hint style="info" %}
If the connection is subscribed to a broadcast the disconnect function will automatically unsubscribe from the broadcast.
{% endhint %}

### Destroy a connection

You can destroy a connection by using the destroy function.

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
...
connection.destroy();
```

{% hint style="info" %}
If the connection is subscribed to a broadcast, the destroy function will automatically unsubscribe from the broadcast.
{% endhint %}

### Pause a stream

You can pause a stream by using the pause function.

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
...
connection.pause();
```

{% hint style="danger" %}
**This function does not work for broadcasts!** Broadcasts have their [own pause](https://zyno-studio.gitbook.io/discord-audio/classes/broken-reference) function.
{% endhint %}

### Resuming a stream

You can resume a stream by using the resume function.

```javascript
const {Connection} = require('discordaudio');
const discord = require('discord.js');

const client = new discord.Client({intents: [discord.Intents.FLAGS.GUILDS]});

const channel = client.channels.cache.get('0123456789');

const connection = new Connection(channel, {
    selfDeaf: true,
    selfMute: false
});
...
connection.resume();
```

{% hint style="danger" %}
**This function does not work for broadcasts!** Broadcasts have their [own resume](https://zyno-studio.gitbook.io/discord-audio/classes/broken-reference) function.
{% endhint %}

### Event listeners

The Connection class also has 6 events:

* play: When the stream of the connection starts playing.
  * Returns the stream that plays (not for broadcasts)
* end: When the stream of the connection ended.
  * Returns the stream that ended (not for broadcasts)
* disconnect: When the bot got disconnected from the connection.
  * Returns the channel id
* destroy: When the connection got destroyed.
  * Returns the channel id
* subscribe: When the connection got subscribed to a broadcast.
* unsubscribe: When the connection got unsubscribed from a broadcast.

```javascript
...
connection.on('play', stream => {
    if(stream) console.log(`Started playing ${stream}`);
    else console.log(`Started playing a broadcast`);
});
connection.on('end', stream => {
    if(stream) console.log(`The stream ${stream} ended`);
    else console.log(`The broadcast ended`);
});

connection.on('disconnect', channelid => console.log(`Disconnected from the channel with the id ${channelid}`));

connection.on('destroy', channelid => console.log(`Destroyed the connection with the channel witht the id ${channelid}`));

connection.on('subscribe', () => console.log(`Subscribed to a broadcast`));

connection.on('unsubscribe', () => console.log(`Unsubscribed to a broadcast`));
```


---

# 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://zyno-studio.gitbook.io/discord-audio/classes/connection.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.