X Space Downloader

A Python CLI tool that downloads X (Twitter) Space recordings and outputs them as MP3 files.

Features

• Download X Space recordings as MP3 files
• Support for authenticated downloads using cookies
• Simple command-line interface
• Clear error messages

Installation

Prerequisites

• Python 3.8 or higher
• ffmpeg (required by yt-dlp for audio conversion)

Install ffmpeg:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

Install the tool

git clone https://github.com/synapz-org/x-space-downloader.git
cd x-space-downloader
pip install -e .

Usage

Basic usage

x-space-dl https://x.com/i/spaces/1ZkKzZWnVRRKv

This will download the Space recording and save it as space_1ZkKzZWnVRRKv.mp3 in the current directory.

With authentication (recommended)

For better reliability and access to private Spaces, provide cookies from your logged-in X session:

x-space-dl --cookies cookies.txt https://x.com/i/spaces/1ZkKzZWnVRRKv

Specify output directory

x-space-dl --output ~/Downloads https://x.com/i/spaces/1ZkKzZWnVRRKv

Full options

x-space-dl --help

Exporting Cookies

To download Spaces that require authentication, you need to export cookies from your logged-in X session.

Method 1: Browser Extension (Easiest)

1. Install a cookie export extension:

   • Chrome/Edge: Get cookies.txt LOCALLY
   • Firefox: cookies.txt

2. Log in to X (twitter.com or x.com)

3. Click the extension icon and export cookies

4. Save as cookies.txt

Method 2: Manual Export (Advanced)

1. Log in to X
2. Open Developer Tools (F12)
3. Go to Application/Storage → Cookies
4. Copy cookies in Netscape format to a file

Requirements

• Python 3.8+
• yt-dlp
• click
• ffmpeg (system dependency)

Supported URLs

The tool supports X Space URLs in these formats:

• https://x.com/i/spaces/{SPACE_ID}
• https://twitter.com/i/spaces/{SPACE_ID}

Note: Only recordings are supported. Live Spaces must be recorded before downloading.

Error Messages

Error	Meaning
"Invalid URL format"	URL doesn't match X Space format
"Failed to download Space"	Recording not found or network error
"Authentication required"	Space requires login (use --cookies)

Development

Running tests

pip install pytest pytest-mock
pytest

Project structure

x-space-downloader/
├── src/
│   ├── main.py          # CLI entry point
│   ├── downloader.py    # yt-dlp wrapper
│   └── validator.py     # URL validation
├── tests/
│   ├── test_main.py
│   ├── test_downloader.py
│   └── test_validator.py
└── docs/
    └── plans/           # Design documents

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Troubleshooting

"ffmpeg not found"

Install ffmpeg using your system's package manager (see Installation section).

"Video unavailable"

The Space recording may have been deleted or is private. Try using the --cookies option.

"Authentication required"

Export cookies from your logged-in X session and use the --cookies option.

Acknowledgments

Built with:

• yt-dlp - Media downloader
• Click - CLI framework