# ICapture

<a id="icapture"></a>

# ICapture

```cpp
#include <icy/av/icapture.h>

class ICapture
```

[Defined in src/av/include/icy/av/icapture.h:31](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L31)

> **Inherits:** [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter), [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable)
> **Subclassed by:** [`MediaCapture`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#mediacapture)

Abstract interface for audio and video capture devices.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`emitter`](#emitter-5) | `variable` | Declared here |
| [`ICapture`](#icapture-1) | `function` | Declared here |
| [`~ICapture`](#icapture-2) | `function` | Declared here |
| [`start`](#start-15) | `function` | Declared here |
| [`stop`](#stop-7) | `function` | Declared here |
| [`openFile`](#openfile) | `function` | Declared here |
| [`close`](#close-7) | `function` | Declared here |
| [`getEncoderFormat`](#getencoderformat) | `function` | Declared here |
| [`getEncoderAudioCodec`](#getencoderaudiocodec) | `function` | Declared here |
| [`getEncoderVideoCodec`](#getencodervideocodec) | `function` | Declared here |
| [`openAudio`](#openaudio) | `function` | Declared here |
| [`openVideo`](#openvideo) | `function` | Declared here |
| [`onStreamStateChange`](#onstreamstatechange-5) | `function` | Declared here |
| [`openStream`](#openstream) | `function` | Declared here |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter) | `variable` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`start`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#start-21) | `function` | Inherited from [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable) |
| [`stop`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#stop-12) | `function` | Inherited from [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable) |

## Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1)  | Construct the adapter, binding it to the given packet signal. |
| `function` | [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) `virtual` `inline` |  |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) `virtual` | Emit a mutable raw buffer as a packet. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) `virtual` | Emit a read-only raw buffer as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) `virtual` | Emit a string as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) `virtual` | Emit a flag-only packet carrying no payload data. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) `virtual` | Emit an existing packet directly onto the outgoing signal. |
| `function` | [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter)  | Returns a reference to the outgoing packet signal. |
| `function` | [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) `virtual` `const` | Returns how this adapter treats incoming packet lifetime. Most adapters are synchronous and therefore only borrow the packet for the current call chain. Queue-style adapters override this to advertise that they clone before deferred use. Callers may treat the first adapter reporting Cloned or Retained as the explicit ownership boundary in the stream graph. |
| `function` | [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) `virtual` `inline` | Called by the [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) to notify when the internal [Stream](https://auscaster.com/icey/docs/api-reference/icy-Stream.md#stream) state changes. On receiving the Stopped state, it is the responsibility of the adapter to have ceased all outgoing packet transmission, especially in multi-thread scenarios. |
| `variable` | [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter)  |  |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3)  | NonCopyable and NonMovable. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72)  | Deleted assignment operator. |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4)  | Deleted constructor. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73)  | Deleted assignment operator. |

## Inherited from [`Startable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#startable)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`start`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#start-21) `virtual` | Starts the object (e.g. begins processing or listening). |
| `function` | [`stop`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#stop-12) `virtual` | Stops the object (e.g. halts processing or closes resources). |

## Public Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) | [`emitter`](#emitter-5)  |  |

---

<a id="emitter-5"></a>

### emitter

```cpp
PacketSignal emitter
```

Type: [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal)

[Defined in src/av/include/icy/av/icapture.h:89](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L89)

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`ICapture`](#icapture-1) `inline` |  |
|  | [`~ICapture`](#icapture-2) `virtual` | Defaulted destructor. |
| `void` | [`start`](#start-15) `virtual` `override` | Start capturing and emitting packets. |
| `void` | [`stop`](#stop-7) `virtual` `override` | Stop capturing and release device resources. |
| `void` | [`openFile`](#openfile) `virtual` `inline` | Open a media file as the capture source. |
| `void` | [`close`](#close-7) `virtual` `inline` | Release the capture source and any associated resources. |
| `void` | [`getEncoderFormat`](#getencoderformat) `virtual` | Populate `iformat` with the encoder-ready format derived from this capture source. |
| `void` | [`getEncoderAudioCodec`](#getencoderaudiocodec) `virtual` `inline` | Populate `params` with the encoder-ready audio codec parameters. |
| `void` | [`getEncoderVideoCodec`](#getencodervideocodec) `virtual` `inline` | Populate `params` with the encoder-ready video codec parameters. |
| `void` | [`openAudio`](#openaudio) `virtual` `inline` | Open an audio capture device with the given parameters. |
| `void` | [`openVideo`](#openvideo) `virtual` `inline` | Open a video capture device with the given parameters. |
| `void` | [`onStreamStateChange`](#onstreamstatechange-5) `virtual` `inline` `override` | React to [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) state transitions by starting or stopping capture. |

---

<a id="icapture-1"></a>

### ICapture

`inline`

```cpp
inline ICapture()
```

[Defined in src/av/include/icy/av/icapture.h:35](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L35)

---

<a id="icapture-2"></a>

### ~ICapture

`virtual`

```cpp
virtual ~ICapture() = default
```

[Defined in src/av/include/icy/av/icapture.h:39](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L39)

Defaulted destructor.

---

<a id="start-15"></a>

### start

`virtual` `override`

```cpp
virtual void start() override
```

[Defined in src/av/include/icy/av/icapture.h:42](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L42)

Start capturing and emitting packets.

#### Reimplements

- [`Startable::start`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#start-21)

#### Reimplemented by

- [`MediaCapture::start`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#start-18)

---

<a id="stop-7"></a>

### stop

`virtual` `override`

```cpp
virtual void stop() override
```

[Defined in src/av/include/icy/av/icapture.h:45](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L45)

Stop capturing and release device resources.

#### Reimplements

- [`Startable::stop`](https://auscaster.com/icey/docs/api-reference/icy-basic-Startable.md#stop-12)

#### Reimplemented by

- [`MediaCapture::stop`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#stop-9)

---

<a id="openfile"></a>

### openFile

`virtual` `inline`

```cpp
virtual inline void openFile(const std::string & file)
```

[Defined in src/av/include/icy/av/icapture.h:49](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L49)

Open a media file as the capture source.

#### Reimplemented by

- [`MediaCapture::openFile`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#openfile-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `file` | `const std::string &` | Path to the media file. |

---

<a id="close-7"></a>

### close

`virtual` `inline`

```cpp
virtual inline void close()
```

[Defined in src/av/include/icy/av/icapture.h:52](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L52)

Release the capture source and any associated resources.

#### Reimplemented by

- [`MediaCapture::close`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#close-12)

---

<a id="getencoderformat"></a>

### getEncoderFormat

`virtual`

```cpp
virtual void getEncoderFormat(Format & iformat)
```

[Defined in src/av/include/icy/av/icapture.h:56](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L56)

Populate `iformat` with the encoder-ready format derived from this capture source.

#### Reimplemented by

- [`MediaCapture::getEncoderFormat`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#getencoderformat-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `iformat` | [`Format`](https://auscaster.com/icey/docs/api-reference/icy-av-Format.md#format-5) & | Output [Format](https://auscaster.com/icey/docs/api-reference/icy-av-Format.md#format-5) struct to fill. |

---

<a id="getencoderaudiocodec"></a>

### getEncoderAudioCodec

`virtual` `inline`

```cpp
virtual inline void getEncoderAudioCodec(AudioCodec & params)
```

[Defined in src/av/include/icy/av/icapture.h:60](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L60)

Populate `params` with the encoder-ready audio codec parameters.

#### Reimplemented by

- [`MediaCapture::getEncoderAudioCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#getencoderaudiocodec-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `params` | [`AudioCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-AudioCodec.md#audiocodec) & | Output [AudioCodec](https://auscaster.com/icey/docs/api-reference/icy-av-AudioCodec.md#audiocodec) struct to fill. |

---

<a id="getencodervideocodec"></a>

### getEncoderVideoCodec

`virtual` `inline`

```cpp
virtual inline void getEncoderVideoCodec(VideoCodec & params)
```

[Defined in src/av/include/icy/av/icapture.h:64](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L64)

Populate `params` with the encoder-ready video codec parameters.

#### Reimplemented by

- [`MediaCapture::getEncoderVideoCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#getencodervideocodec-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `params` | [`VideoCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-VideoCodec.md#videocodec) & | Output [VideoCodec](https://auscaster.com/icey/docs/api-reference/icy-av-VideoCodec.md#videocodec) struct to fill. |

---

<a id="openaudio"></a>

### openAudio

`virtual` `inline`

```cpp
virtual inline void openAudio(const std::string & device, const AudioCodec & params)
```

[Defined in src/av/include/icy/av/icapture.h:69](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L69)

Open an audio capture device with the given parameters.

#### Reimplemented by

- [`AudioCapture::openAudio`](https://auscaster.com/icey/docs/api-reference/icy-av-AudioCapture.md#openaudio-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `device` | `const std::string &` | The platform audio device identifier. |
| `params` | const [`AudioCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-AudioCodec.md#audiocodec) & | The desired capture parameters. |

---

<a id="openvideo"></a>

### openVideo

`virtual` `inline`

```cpp
virtual inline void openVideo(const std::string & device, const VideoCodec & params)
```

[Defined in src/av/include/icy/av/icapture.h:74](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L74)

Open a video capture device with the given parameters.

#### Reimplemented by

- [`VideoCapture::openVideo`](https://auscaster.com/icey/docs/api-reference/icy-av-VideoCapture.md#openvideo-1)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `device` | `const std::string &` | The platform video device identifier. |
| `params` | const [`VideoCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-VideoCodec.md#videocodec) & | The desired capture parameters. |

---

<a id="onstreamstatechange-5"></a>

### onStreamStateChange

`virtual` `inline` `override`

```cpp
virtual inline void onStreamStateChange(const PacketStreamState & state) override
```

[Defined in src/av/include/icy/av/icapture.h:77](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L77)

React to [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) state transitions by starting or stopping capture.

#### Reimplements

- [`PacketStreamAdapter::onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1)

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `void` | [`openStream`](#openstream) `virtual` `inline` |  |

---

<a id="openstream"></a>

### openStream

`virtual` `inline`

```cpp
virtual inline void openStream(const std::string & filename, const AVInputFormat * inputFormat, AVDictionary ** formatParams)
```

[Defined in src/av/include/icy/av/icapture.h:92](https://github.com/auscaster/icey/blob/main/src/av/include/icy/av/icapture.h#L92)

#### Reimplemented by

- [`MediaCapture::openStream`](https://auscaster.com/icey/docs/api-reference/icy-av-MediaCapture.md#openstream-1)