Practice Now
TensorFlow
contrib
ffmpeg
decode_audio
alternative

tf.contrib.ffmpeg.decode_audio replacement?

ML System Design practice on Codemia

Design recommenders, ranking systems and training pipelines the way ML interviews actually ask for them, with worked solutions.

Practice ML system design
TensorFlow & Keras

Introduction

tf.contrib.ffmpeg.decode_audio was removed when tf.contrib was deprecated in TensorFlow 2.0. The recommended replacements are tf.audio.decode_wav for WAV files (built into TensorFlow), tensorflow-io (tfio.audio) for MP3, FLAC, OGG, and other formats, or external libraries like librosa, soundfile, or pydub for preprocessing audio before feeding it into TensorFlow. For most pipelines, preprocessing with librosa or soundfile and passing NumPy arrays to TensorFlow is the simplest migration path.

Original tf.contrib Code

python
1# TensorFlow 1.x — no longer works in TF2
2import tensorflow as tf
3
4audio_binary = tf.io.read_file("audio.mp3")
5audio, sample_rate = tf.contrib.ffmpeg.decode_audio(
6    audio_binary,
7    file_format="mp3",
8    samples_per_second=16000,
9    channel_count=1
10)
11# audio shape: (samples, channels)

This function used FFmpeg internally to decode audio files of any format into tensors. It was removed along with the entire tf.contrib module in TF2.

Replacement 1: tf.audio.decode_wav (WAV Only)

python
1import tensorflow as tf
2
3# Read and decode a WAV file
4audio_binary = tf.io.read_file("audio.wav")
5audio, sample_rate = tf.audio.decode_wav(audio_binary, desired_channels=1)
6
7print(audio.shape)        # (samples, 1)
8print(sample_rate.numpy()) # 16000 or whatever the file's rate is
9
10# Use in a tf.data pipeline
11def load_wav(file_path):
12    audio_binary = tf.io.read_file(file_path)
13    audio, sr = tf.audio.decode_wav(audio_binary, desired_channels=1)
14    return tf.squeeze(audio, axis=-1)  # (samples,)
15
16dataset = tf.data.Dataset.from_tensor_slices(wav_files)
17dataset = dataset.map(load_wav)

tf.audio.decode_wav is built into TensorFlow and requires no extra dependencies. It only supports WAV format (16-bit PCM). Convert other formats to WAV first if you want to use this function.

Replacement 2: TensorFlow I/O (Multiple Formats)

bash
pip install tensorflow-io
python
1import tensorflow as tf
2import tensorflow_io as tfio
3
4# Decode MP3
5audio_binary = tf.io.read_file("audio.mp3")
6audio = tfio.audio.decode_mp3(audio_binary)
7print(audio.shape)  # (samples, channels)
8
9# Decode FLAC
10audio_binary = tf.io.read_file("audio.flac")
11audio = tfio.audio.decode_flac(audio_binary)
12
13# Decode OGG/Vorbis
14audio_binary = tf.io.read_file("audio.ogg")
15audio = tfio.audio.decode_vorbis(audio_binary)
16
17# Resample to target sample rate
18audio_resampled = tfio.audio.resample(audio, rate_in=44100, rate_out=16000)
19
20# Use in a tf.data pipeline
21def load_mp3(file_path):
22    audio_binary = tf.io.read_file(file_path)
23    audio = tfio.audio.decode_mp3(audio_binary)
24    audio = tf.cast(audio, tf.float32) / 32768.0  # normalize to [-1, 1]
25    audio = tfio.audio.resample(audio, rate_in=44100, rate_out=16000)
26    return tf.squeeze(audio, axis=-1)
27
28dataset = tf.data.Dataset.from_tensor_slices(mp3_files)
29dataset = dataset.map(load_mp3, num_parallel_calls=tf.data.AUTOTUNE)

tensorflow-io is the closest replacement to tf.contrib.ffmpeg. It provides TensorFlow-native ops for decoding audio, making it compatible with tf.data pipelines and tf.function.

Replacement 3: librosa (Preprocessing)

bash
pip install librosa
python
1import librosa
2import numpy as np
3import tensorflow as tf
4
5# Load any audio format (MP3, WAV, FLAC, OGG, etc.)
6audio, sr = librosa.load("audio.mp3", sr=16000, mono=True)
7print(audio.shape)  # (samples,) — float32 numpy array
8print(sr)           # 16000
9
10# Convert to TensorFlow tensor
11audio_tensor = tf.convert_to_tensor(audio, dtype=tf.float32)
12
13# Extract mel spectrogram for model input
14mel_spec = librosa.feature.melspectrogram(y=audio, sr=sr, n_mels=128)
15log_mel = librosa.power_to_db(mel_spec, ref=np.max)
16mel_tensor = tf.convert_to_tensor(log_mel, dtype=tf.float32)
17
18# Batch processing
19def preprocess_audio(file_path):
20    audio, sr = librosa.load(file_path, sr=16000, mono=True)
21    mel = librosa.feature.melspectrogram(y=audio, sr=sr, n_mels=128)
22    return librosa.power_to_db(mel, ref=np.max)
23
24# Use with tf.data via py_function
25def tf_load_audio(file_path):
26    audio = tf.py_function(
27        lambda p: preprocess_audio(p.numpy().decode()),
28        [file_path],
29        tf.float32
30    )
31    return audio
32
33dataset = tf.data.Dataset.from_tensor_slices(file_paths)
34dataset = dataset.map(tf_load_audio)

librosa supports every audio format via FFmpeg/SoundFile backends. It runs outside TensorFlow's graph, so wrap calls in tf.py_function for tf.data pipelines.

Replacement 4: soundfile (Fast WAV/FLAC)

bash
pip install soundfile
python
1import soundfile as sf
2import tensorflow as tf
3
4# Read WAV, FLAC, or OGG
5audio, sr = sf.read("audio.wav")  # numpy array
6print(audio.shape, sr)
7
8# Convert to tensor
9audio_tensor = tf.convert_to_tensor(audio, dtype=tf.float32)
10
11# Write audio
12sf.write("output.wav", audio, sr)

soundfile is faster than librosa for reading/writing but supports fewer formats (WAV, FLAC, OGG — not MP3 without FFmpeg).

Replacement 5: pydub + FFmpeg

bash
pip install pydub
# Also requires: apt install ffmpeg (or brew install ffmpeg)
python
1from pydub import AudioSegment
2import numpy as np
3import tensorflow as tf
4
5# Load any format
6audio = AudioSegment.from_file("audio.mp3")
7
8# Convert to mono, set sample rate
9audio = audio.set_channels(1).set_frame_rate(16000)
10
11# Convert to numpy array
12samples = np.array(audio.get_array_of_samples(), dtype=np.float32)
13samples = samples / 32768.0  # normalize 16-bit audio to [-1, 1]
14
15# Convert to TensorFlow tensor
16audio_tensor = tf.convert_to_tensor(samples)

Migration Comparison

Featuretf.contrib.ffmpegtf.audiotensorflow-iolibrosa
MP3 supportYesNoYesYes
WAV supportYesYesYesYes
FLAC/OGGYesNoYesYes
TF-native opsYesYesYesNo (py_function)
tf.data compatibleYesYesYesVia wrapper
Extra installNo (bundled)NoYesYes

Common Pitfalls

  • Assuming tf.audio.decode_wav handles MP3: decode_wav only supports WAV files (16-bit PCM). For MP3, FLAC, or OGG, use tensorflow-io or librosa. Passing an MP3 file to decode_wav raises a decoding error.
  • Not normalizing audio data: Different decoders return different value ranges. decode_wav returns float32 in [-1, 1]. librosa.load returns float32 in [-1, 1]. Raw soundfile may return int16 in [-32768, 32767]. Always normalize to a consistent range before model input.
  • Using librosa inside tf.function: librosa is a NumPy-based library and cannot run inside TensorFlow's graph. Wrap it in tf.py_function for tf.data pipelines. This disables graph optimization for that op.
  • Installing tensorflow-io version mismatch: tensorflow-io version must match your TensorFlow version. tensorflow-io==0.34 requires TF 2.14, tensorflow-io==0.35 requires TF 2.15. Version mismatches cause import errors.
  • Forgetting to install FFmpeg for pydub/librosa: pydub and librosa (for MP3) require FFmpeg installed on the system. Without it, MP3 decoding fails with FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'.

Summary

  • tf.contrib.ffmpeg.decode_audio was removed in TensorFlow 2.0
  • Use tf.audio.decode_wav for WAV files (built-in, no dependencies)
  • Use tensorflow-io (tfio.audio.decode_mp3) for MP3/FLAC/OGG with TF-native ops
  • Use librosa for flexible preprocessing with any audio format (wrap in tf.py_function for tf.data)
  • Use soundfile for fast WAV/FLAC reading without the overhead of librosa
  • Match tensorflow-io versions to your TensorFlow version to avoid import errors
Related reading
Free course
Beginner
7 lessons
2 hours
Tackling System Design Interview Problems

A short course that equips you with the skills to approach system design interviews methodically.

Start the free course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

ML System Design practice on Codemia

Design recommenders, ranking systems and training pipelines the way ML interviews actually ask for them, with worked solutions.

Practice ML system design
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.