Lamer

Ruby FFI bindings for the LAME MP3 encoder library.

Encode audio to MP3 directly from Ruby without shelling out to a command line tool. Supports encoding from WAV files, raw PCM data, or re-encoding existing MP3 files.

Requirements

Ruby 3.2 or later
libmp3lame library installed on your system

Installation

First, install the LAME library:

macOS (Homebrew)

brew install lame

Ubuntu/Debian

sudo apt-get install libmp3lame-dev

Fedora/RHEL/CentOS

sudo dnf install lame-devel

Then add the gem to your Gemfile:

gem 'lamer'

Or install it directly:

gem install lamer

Quick Start

require 'lamer'

# One-liner encoding
Lamer.encode("input.wav", "output.mp3", bitrate: 192, mode: :stereo)

# One-liner decoding
Lamer.decode("input.mp3", "output.wav")

# With ID3 tags
Lamer.encode("input.wav", "output.mp3", bitrate: 192, id3: { title: "My Song", artist: "My Artist" })

# Block syntax for more control
Lamer.encode("input.wav", "output.mp3") do |l|
  l.bitrate(256)
  l.vbr_quality(2)
  l.id3(title: "My Song", artist: "My Artist", album: "My Album")
end

Usage

Basic Encoding

require 'lamer'

lamer = Lamer.new
lamer.bitrate(128)
lamer.input_file("audio.wav")
lamer.output_file("audio.mp3")
lamer.convert!

VBR Encoding

lamer = Lamer.new
lamer.vbr_quality(2)  # 0 = best quality, 9 = smallest file
lamer.input_file("audio.wav")
lamer.output_file("audio.mp3")
lamer.convert!

Setting Quality and Mode

lamer = Lamer.new
lamer.bitrate(320)
lamer.encode_quality(:high)  # or 0-9, where 0 is best
lamer.mode(:stereo)          # :mono, :stereo, :joint, :auto
lamer.input_file("audio.wav")
lamer.output_file("audio.mp3")
lamer.convert!

ID3 Tags

lamer = Lamer.new
lamer.bitrate(192)
lamer.id3(
  title: "Song Title",
  artist: "Artist Name",
  album: "Album Name",
  year: 2024,
  track_number: 1,
  genre: "Rock"
)
lamer.input_file("audio.wav")
lamer.output_file("audio.mp3")
lamer.convert!

Re-encoding MP3 Files

lamer = Lamer.new
lamer.bitrate(64)
lamer.mode(:mono)
lamer.input_file("highquality.mp3")
lamer.output_file("lowquality.mp3")
lamer.convert!

Decoding MP3 to WAV

lamer = Lamer.new
lamer.decode_mp3!
lamer.input_file("audio.mp3")
lamer.output_file("audio.wav")
lamer.decode!

In-Memory Encoding

Encode PCM samples directly without file I/O:

lamer = Lamer.new
lamer.bitrate(128)

# 16-bit signed integer samples
left_channel = [0, 1000, 2000, 3000, ...]
right_channel = [0, 1000, 2000, 3000, ...]

mp3_data = lamer.encode_buffer(left_channel, right_channel)
File.binwrite("output.mp3", mp3_data)

Float Sample Encoding

For audio processing pipelines that use floating point samples:

lamer = Lamer.new
lamer.bitrate(256)

# Float samples in range -1.0 to 1.0
left_channel = [0.0, 0.5, 1.0, 0.5, ...]
right_channel = [0.0, 0.5, 1.0, 0.5, ...]

mp3_data = lamer.encode_float_buffer(left_channel, right_channel)

Available Options

Bitrate

Valid bitrates in kbps: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320

lamer.bitrate(128)

Sample Rate

Valid sample rates in kHz: 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, 48

lamer.sample_rate(44.1)

VBR Quality

Values 0-9, where 0 is highest quality and 9 is smallest file size.

lamer.vbr_quality(2)

Encoding Quality

Values 0-9, where 0 is slowest/best and 9 is fastest/worst. Also accepts :high (2) and :fast (7).

lamer.encode_quality(:high)

Channel Mode

Available modes: :mono, :stereo, :joint, :auto, :mid_side

lamer.mode(:joint)

Filters

Set highpass and lowpass filter frequencies in kHz:

lamer.highpass(0.1)   # 100 Hz
lamer.lowpass(16.0)   # 16 kHz

Version Information

Lamer.lame_version  # Returns the LAME library version string

Author

Mauricio Gomes

License

MIT License

lamer

Runtime