Membrane PortAudio Plugin

https://hexdocs.pm/membrane_portaudio_plugin/
Admin
A Membrane Framework plugin that captures and plays sound using the multiplatform PortAudio library...
Tokens:2,734
Snippets:21
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install PortAudio Dependencies on Ubuntu

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Manual installation commands for PortAudio development libraries on Ubuntu. These packages are required for the precompiled PortAudio build to function correctly. Ensure `alsa-lib` and `portaudio19-dev` are installed.

```bash
sudo apt-get install alsa
sudo apt-get install portaudio19-dev
```

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

### Install PortAudio Dependencies on Arch/Manjaro

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Manual installation commands for PortAudio development libraries on Arch Linux and Manjaro. These commands use `pacman` to install `alsa-lib` and `portaudio`.

```bash
pacman -S alsa-lib
pacman -S portaudio
```

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

### Install Membrane PortAudio Plugin

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Add the Membrane PortAudio plugin dependency to your `mix.exs` file. After adding the line, run `mix deps.get` to fetch the dependency. This plugin relies on the PortAudio library, which is usually automatically linked. Manual installation instructions for PortAudio are provided for Linux and macOS if issues arise.

```elixir
 {:membrane_portaudio_plugin, "~> 0.19.2"}
```

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

### Install PortAudio Dependencies (Ubuntu)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

Commands to install necessary PortAudio development libraries on Ubuntu systems. ALSA (alsa-lib) is required for the precompiled build of the PortAudio plugin to work correctly. These packages ensure PortAudio and its ALSA backend are available.

```bash
sudo apt-get install alsa
copy
```

```bash
sudo apt-get install portaudio19-dev
copy
```

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

### Install PortAudio Dependencies on macOS

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Manual installation command for PortAudio development libraries on macOS using Homebrew. This command installs the necessary PortAudio package for the plugin to function.

```bash
brew install portaudio
```

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

### Install Membrane PortAudio Plugin (Elixir)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

Instructions to add the Membrane PortAudio plugin to your project's dependencies in `mix.exs`. This ensures the plugin is available for use in your Elixir project. After adding the line, run `mix deps.get` to fetch the dependency.

```elixir
	{:membrane_portaudio_plugin, "~> 0.19.2"}copy
```

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

### Install PortAudio Dependencies (MacOS)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

Command to install the PortAudio library on macOS using Homebrew. This ensures the necessary audio I/O capabilities are available for the Membrane PortAudio plugin.

```bash
brew install portaudio
copy
```

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

### Forward Audio Input to Output Pipeline (Elixir)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

An Elixir pipeline using Membrane.js to forward audio from the default input device to the default output device. This example uses `Membrane.PortAudio.Source` for input and `Membrane.PortAudio.Sink` for output. Caution is advised due to potential audio feedback.

```elixir
defmodule Membrane.ReleaseTest.Pipeline do
  use Membrane.Pipeline

  alias Membrane.PortAudio

  @impl true
  def handle_init(_ctx, _opts) do
    structure =
      child(:pa_src, PortAudio.Source)
      |> child(:pa_sink, PortAudio.Sink)

    {[spec: structure], %{}}
  end
endcopy
```

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

### Install PortAudio Dependencies (Arch/Manjaro)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

Commands to install PortAudio and its ALSA-related libraries on Arch Linux or Manjaro. These packages are essential for the Membrane PortAudio plugin to function on these distributions.

```bash
pacman -S alsa-lib
copy
```

```bash
pacman -S portaudio
copy
```

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

### Membrane Pipeline for Audio Input to Output

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Elixir pipeline example using Membrane to forward sound from the default input device to the default output device. It uses `Membrane.PortAudio.Source` for input and `Membrane.PortAudio.Sink` for output. Caution is advised to avoid audio feedback by using headphones.

```elixir
defmodule Membrane.ReleaseTest.Pipeline do
  use Membrane.Pipeline

  alias Membrane.PortAudio

  @impl true
  def handle_init(_ctx, _opts) do
    structure =
      child(:pa_src, PortAudio.Source)
      |> child(:pa_sink, PortAudio.Sink)

    {[spec: structure], %{}}
  end
end
```

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

### Membrane Pipeline for Raw File Playback

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Elixir pipeline example using Membrane to play a raw audio file to the default output device. It utilizes `Membrane.Element.File.Source` to read the file and `Membrane.PortAudio.Sink` to output the audio. Ensure the raw file exists at the specified location.

```elixir
defmodule Membrane.ReleaseTest.Pipeline do
  use Membrane.Pipeline

  alias Membrane.PortAudio

  @impl true
  def handle_init(_ctx, _opts) do
    structure = 
      child(:file_src, %Membrane.Element.File.Source{location: "file.raw"})
      |> child(:pa_sink, PortAudio.Sink)
    
    {[spec: structure], %{}}
  end
end
```

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

### Enable Soundcard Tests (Elixir)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

Command to run tests that require actual soundcard interaction with the Membrane PortAudio plugin. These tests are disabled by default and require at least one input and output sound card to be present. Use the `--include soundcard` flag with `mix test`.

```bash
mix test --include soundcardcopy
```

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

### Membrane PortAudio Options Function

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

Retrieves a keyword list describing the available configuration options for the Membrane PortAudio module. This function is useful for understanding and dynamically configuring the plugin.

```Elixir
iex(1)> alias Membrane.PortAudio.Source
Membrane.PortAudio.Source
iex(2)> Source.options()
[device_id: {:integer, :defaultcopy}, endpoint_id: {:nil, :nilcopy}, portaudio_buffer_size: {:pos_integer, :copy}, latency: {:atom, {:one_of, [:low, :high, :copy]}}, sample_format: {:atom, {:one_of, [:u8le, :s8le, :s16le, :s24le, :s32le, :f32le, :copy]}}, sample_rate: {:integer, :non_neg_copy}, channels: {:range, {1, 2, :copy}}]
```

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

### Enable Soundcard Tests

Source: https://hexdocs.pm/membrane_portaudio_plugin/readme

Command to run tests that utilize PortAudio functionality, requiring actual sound cards. These tests are disabled by default. Use the `--include soundcard` flag with `mix test` to enable them.

```bash
mix test --include soundcard
```

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

### Membrane PortAudio Plugin Functions

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

Provides utility functions for the Membrane PortAudio plugin.

```APIDOC
## Membrane PortAudio Plugin Functions

### `options()`

__ View Source
```elixir
@spec options() :: keyword()
```

Returns description of options available for this module.
```

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

### Membrane.PortAudio.Source Element Options

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

This section details the configurable options for the Membrane.PortAudio.Source element, which captures audio via the PortAudio library.

```APIDOC
## Membrane.PortAudio.Source Element Options

This element captures audio using the multi-platform PortAudio library.

### Element Options (`Membrane.PortAudio.Source.t/0`)

- **`device_id`** (integer() | :defaultcopy) - Required/Optional - PortAudio device id. Defaults to the default input device. You can list available devices with `mix pa_devices` or `Membrane.PortAudio.print_devices/0`.
- **`endpoint_id`** (nilcopy) - Required/Optional - Deprecated. Please use device_id instead.
- **`portaudio_buffer_size`** (pos_integer()copy) - Required/Optional - Size of the PortAudio buffer (in frames). Default value: `256`.
- **`latency`** (:low | :highcopy) - Required/Optional - Latency of the input device. Default value: `:high`.
- **`sample_format`** (sample_format()copy) - Required/Optional - Sample format to output. Default value: `:s16le`.
- **`sample_rate`** (non_neg_integer()copy) - Required/Optional - Sample rate to output. If not set, device's default sample rate will be used. Default value: `nil`.
- **`channels`** (1..2copy) - Required/Optional - Number of channels to output. If not set, device's default will be used. Default value: `nil`.

### Pads

- **`:output`**
  - Accepted formats: `%RawAudio{sample_format: format} when format in @sample_formats`
  - Direction: `:output`
  - Availability: `:always`
  - Flow control: `:push`
```

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

### Membrane PortAudio Source Element Options

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

Defines the configuration options for the Membrane PortAudio Source element. These options control aspects like the audio device, buffer size, latency, sample format, sample rate, and number of channels. Default values are provided for most options.

```Elixir
iex(1)> alias Membrane.PortAudio.Source
Membrane.PortAudio.Source
iex(2)> Source.start_link(%{device_id: 1, sample_format: :s32le})
{:ok, pid}
```

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

### Play Raw Audio File Pipeline (Elixir)

Source: https://hexdocs.pm/membrane_portaudio_plugin/index

An Elixir pipeline using Membrane.js to play a raw audio file to the default output device. It utilizes `Membrane.Element.File.Source` to read the file and `Membrane.PortAudio.Sink` to play it.

```elixir
defmodule Membrane.ReleaseTest.Pipeline do
  use Membrane.Pipeline

  alias Membrane.PortAudio

  @impl true
  def handle_init(_ctx, _opts) do
    structure = 
      child(:file_src, %Membrane.Element.File.Source{location: "file.raw"})
      |> child(:pa_sink, PortAudio.Sink)
    
    {[spec: structure], %{}}
  end
endcopy
```

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

### Membrane PortAudio Source Struct Type

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

Defines the structure for the Membrane PortAudio Source element, including its configuration options. This type is used when initializing or inspecting the source element.

```Elixir
iex(1)> alias Membrane.PortAudio.Source
Membrane.PortAudio.Source
iex(2)> %Source{device_id: 0, latency: :low, sample_rate: 44100}
%Membrane.PortAudio.Source{
  channels: nil,
  device_id: 0,
  endpoint_id: nil,
  latency: :low,
  portaudio_buffer_size: 256,
  sample_format: :s16le,
  sample_rate: 44100
}
```

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

### Membrane PortAudio Sample Format Type

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

Specifies the possible audio sample formats supported by the Membrane PortAudio plugin. This type defines the bit depth and endianness of the audio samples.

```Elixir
iex(1)> alias Membrane.PortAudio.Source
Membrane.PortAudio.Source
iex(2)> %RawAudio{sample_format: :s16le}
%RawAudio{channels: nil, pitch: nil, sample_format: :s16le, time: nil, data: nil}
iex(3)> %RawAudio{sample_format: :f32le}
%RawAudio{channels: nil, pitch: nil, sample_format: :f32le, time: nil, data: nil}
```

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

### Membrane PortAudio Plugin Types

Source: https://hexdocs.pm/membrane_portaudio_plugin/Membrane.PortAudio

Defines the data types used within the Membrane PortAudio plugin.

```APIDOC
## Membrane PortAudio Plugin Types

### `sample_format()`

__ View Source
```elixir
@type sample_format() :: :u8le | :s8le | :s16le | :s24le | :s32le | :f32le
```

### `t()`

__ View Source
```elixir
@type t() :: %Membrane.PortAudio.Source{
  channels: 1..2,
  device_id: integer() | :default,
  endpoint_id: nil,
  latency: :low | :high,
  portaudio_buffer_size: pos_integer(),
  sample_format: sample_format(),
  sample_rate: non_neg_integer()
}
```

Struct containing options for `Membrane.PortAudio.Source`
```
Tokens:
Raw