Does Pyutube Support Downloading Audio Only? Complete Implementation Guide

Yes, Pyutube fully supports downloading audio-only tracks from YouTube videos through its dedicated AudioService class and the -a CLI flag.

The hetari/pyutube library provides a robust Python interface for YouTube media extraction, and it does indeed support downloading audio only. This functionality is architected through a clean separation of concerns between audio stream detection and download orchestration. Whether you use the command-line interface or the programmatic API, Pyutube offers multiple pathways to extract audio tracks without retrieving video content.

How Pyutube Implements Audio-Only Downloads

AudioService: The Core Audio Extraction Layer

The AudioService class, located in pyutube/services/AudioService.py, serves as the primary interface for identifying audio streams. It provides a static method that filters a pytubefix.YouTube object to select the first available audio-only stream. This abstraction ensures that downstream components receive a clean audio stream reference without handling complex filter logic.

DownloadService: Orchestrating the Audio Workflow

The DownloadService class in pyutube/services/DownloadService.py manages the actual download execution. It maintains an AudioService instance and an is_audio boolean flag. When is_audio is set to True, the standard download() workflow routes to download_audio(), which invokes AudioService.get_audio_streams() to retrieve the audio stream. The resulting file is then persisted via FileService.

How to Download Audio-Only Files with Pyutube

Command-Line Usage

The CLI exposes the -a or --audio flag to trigger audio-only mode. When this flag is present, the CLI instantiates DownloadService with is_audio=True and executes the audio download path.

# Download only the audio track of a single video

pyutube download https://www.youtube.com/watch?v=VIDEO_ID -a

Programmatic Python API

For Python applications, initialize DownloadService with the is_audio parameter set to True:

from pyutube.services import DownloadService

# Initialise the service with audio‑only mode

dl = DownloadService(
    url="https://www.youtube.com/watch?v=VIDEO_ID",
    path="/tmp",          # destination folder

    quality=None,         # quality is not used for audio‑only

    is_audio=True
)

# Perform the download (returns True on success)

dl.download()

Interactive Prompt Mode

If you omit the -a flag, the library can prompt for format selection. The asking_video_or_audio() function in pyutube/utils.py handles user interaction:

from pyutube.services import DownloadService
from pyutube.utils import asking_video_or_audio

dl = DownloadService(
    url="https://www.youtube.com/watch?v=VIDEO_ID",
    path=".", quality=None
)

# The library will ask you whether you want audio or video

dl.asking_video_or_audio()

Technical Implementation Details

The audio-only feature relies on a specific flag-based routing mechanism. In pyutube/cli.py, the -a/--audio argument sets the is_audio variable, which is passed directly to DownloadService. The service then bypasses video stream selection entirely, delegating to AudioService.get_audio_streams() to filter for audio-only formats. This architecture ensures that memory and bandwidth are optimized by avoiding unnecessary video data retrieval.

Summary

• Pyutube supports downloading audio only through the AudioService and DownloadService classes.
• Use the -a or --audio CLI flag to trigger audio-only mode from the command line.
• Set is_audio=True when instantiating DownloadService programmatically.
• The asking_video_or_audio() utility provides interactive fallback when no format is specified.
• Audio streams are filtered and retrieved via AudioService.get_audio_streams() in pyutube/services/AudioService.py.

Frequently Asked Questions

Does Pyutube support downloading audio only from playlists?

Yes, the audio-only flag works at the playlist level. When you pass -a with a playlist URL, Pyutube iterates through each video and applies the same is_audio=True logic via DownloadService, extracting audio streams for every item in the collection.

What audio format does Pyutube download?

Pyutube relies on pytubefix for stream selection, which typically returns the highest bitrate audio stream available, often in MPEG-4 Audio (m4a) format. The exact codec depends on YouTube's available streams for that specific video.

Can I specify audio quality when using Pyutube?

Currently, the quality parameter in DownloadService is ignored when is_audio=True, as noted in the source code. The AudioService selects the first available audio stream (typically the highest quality) without exposing granular bitrate selection to the end user.

Is the audio-only download feature available in the CLI?

Yes, the feature is fully exposed via the command-line interface. The -a or --audio flag in pyutube/cli.py triggers the audio-only download path, making it accessible without writing Python code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}