# x-spaces-dl
> A powerful command-line tool and Python library for downloading Twitter/X Spaces recordings
[](https://badge.fury.io/py/x-spaces-dl)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## ✨ Features
- 🎙️ Download Twitter/X Spaces recordings (replays)
- 📦 Batch download multiple spaces from a file
- 🎵 Multiple output formats (M4A, MP3, AAC, WAV)
- 📊 Rich metadata embedding (title, host, date, participants)
- 🔄 Resume interrupted downloads
- 🚀 Fast downloads with ffmpeg or pure Python fallback
- 🔐 Guest mode (no login) with automatic fallback to authenticated mode
- 📈 Beautiful progress bars and detailed logging
- ⚙️ Highly configurable via CLI or config file
- 🐍 Use as a library in your Python projects
## 📥 Installation
### From PyPI (recommended)
```bash
pip install x-spaces-dl
```
### From source
```bash
git clone https://github.com/w3Abhishek/x-spaces-dl.git
cd x-spaces-dl
pip install -e .
```
### Optional: Install ffmpeg for faster downloads
- **Ubuntu/Debian**: `sudo apt install ffmpeg`
- **macOS**: `brew install ffmpeg`
- **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)
## 🚀 Quick Start
### Command Line
```bash
# Download a space (guest mode)
x-spaces-dl https://x.com/i/spaces/1234567890
# Download with authentication (if guest mode fails)
x-spaces-dl https://x.com/i/spaces/1234567890 --cookies cookies.txt
# Download multiple spaces from a file
x-spaces-dl --batch urls.txt
# Download as MP3 with metadata
x-spaces-dl https://x.com/i/spaces/1234567890 --format mp3 --embed-metadata
# Custom output filename
x-spaces-dl https://x.com/i/spaces/1234567890 -o "my_space.m4a"
# Show space info without downloading
x-spaces-dl https://x.com/i/spaces/1234567890 --info-only
```
### Python Library
```python
from xspacesdl import XSpacesDL
# Initialize downloader
downloader = XSpacesDL()
# Download a space
downloader.download_space(
"https://x.com/i/spaces/1234567890",
output_file="space.m4a"
)
# Get space metadata
metadata = downloader.get_space_metadata("https://x.com/i/spaces/1234567890")
print(f"Title: {metadata['title']}")
print(f"Host: {metadata['host']}")
```
## 📖 Usage
### Basic Commands
```bash
# Download with default settings
x-spaces-dl <SPACE_URL>
# Specify output file
x-spaces-dl <SPACE_URL> -o output.m4a
# Use authenticated mode with cookies
x-spaces-dl <SPACE_URL> --cookies cookies.txt
# Force guest mode (no fallback)
x-spaces-dl <SPACE_URL> --guest-only
```
### Batch Download
Create a text file with one URL per line:
```text
https://x.com/i/spaces/1234567890
https://x.com/i/spaces/0987654321
https://x.com/i/spaces/1111111111
```
Then run:
```bash
x-spaces-dl --batch urls.txt
```
### Output Formats
```bash
# Convert to MP3
x-spaces-dl <SPACE_URL> --format mp3
# Convert to WAV
x-spaces-dl <SPACE_URL> --format wav
# Keep original M4A
x-spaces-dl <SPACE_URL> --format m4a
```
### Metadata
```bash
# Embed metadata (title, host, date)
x-spaces-dl <SPACE_URL> --embed-metadata
# Save metadata to JSON
x-spaces-dl <SPACE_URL> --save-metadata
# Show info only (no download)
x-spaces-dl <SPACE_URL> --info-only
```
### Advanced Options
```bash
# Custom output directory
x-spaces-dl <SPACE_URL> --output-dir ~/Downloads/Spaces
# Filename template
x-spaces-dl <SPACE_URL> --template "{date}_{host}_{title}"
# Retry failed downloads
x-spaces-dl <SPACE_URL> --retry 3
# Quiet mode (no output)
x-spaces-dl <SPACE_URL> --quiet
# Verbose mode (detailed logging)
x-spaces-dl <SPACE_URL> --verbose
# Dry run (show what would be downloaded)
x-spaces-dl <SPACE_URL> --dry-run
```
### Configuration File
Create `~/.config/xspacesdl/config.yaml`:
```yaml
output_dir: ~/Downloads/Spaces
format: mp3
embed_metadata: true
cookies_file: ~/cookies.txt
retry_attempts: 3
template: "{date}_{host}_{title}"
```
Then simply run:
```bash
x-spaces-dl <SPACE_URL>
```
## 🔐 Authentication
For private spaces or when guest mode fails:
1. **Export cookies from your browser**:
- Install a browser extension like "Get cookies.txt" or "EditThisCookie"
- Visit twitter.com/x.com and login
- Export cookies to `cookies.txt` (Netscape format)
2. **Use cookies with x-spaces-dl**:
```bash
x-spaces-dl <SPACE_URL> --cookies cookies.txt
```
## 🛠️ All CLI Options
```
x-spaces-dl [OPTIONS] [SPACE_URL]
Options:
-o, --output TEXT Output filename
-d, --output-dir PATH Output directory
-b, --batch FILE Batch download from file
-f, --format [m4a|mp3|aac|wav] Output format (default: m4a)
-c, --cookies FILE Path to cookies.txt file
--guest-only Use guest mode only (no auth fallback)
--embed-metadata Embed metadata into audio file
--save-metadata Save metadata to JSON file
--info-only Show space info without downloading
--template TEXT Filename template
--retry INTEGER Retry attempts (default: 3)
--no-resume Disable resume capability
-q, --quiet Quiet mode
-v, --verbose Verbose mode
--dry-run Dry run (no actual download)
--config FILE Config file path
--version Show version
--help Show this message and exit
```
## 📚 Python API
### Basic Usage
```python
from xspacesdl import XSpacesDL
# Initialize
dl = XSpacesDL()
# Download a space
dl.download_space("https://x.com/i/spaces/1234567890")
```
### With Authentication
```python
from xspacesdl import XSpacesDL
# Initialize with cookies
dl = XSpacesDL(cookies_file="cookies.txt")
# Download
dl.download_space("https://x.com/i/spaces/1234567890")
```
### Advanced Usage
```python
from xspacesdl import XSpacesDL
from xspacesdl.config import Config
# Custom configuration
config = Config(
output_dir="./downloads",
format="mp3",
embed_metadata=True,
retry_attempts=5
)
# Initialize with config
dl = XSpacesDL(config=config)
# Get metadata
metadata = dl.get_space_metadata("https://x.com/i/spaces/1234567890")
# Download with custom options
dl.download_space(
"https://x.com/i/spaces/1234567890",
output_file="custom_name.mp3",
format="mp3"
)
```
### Batch Download
```python
from xspacesdl import XSpacesDL
dl = XSpacesDL()
urls = [
"https://x.com/i/spaces/1234567890",
"https://x.com/i/spaces/0987654321",
]
for url in urls:
try:
dl.download_space(url)
print(f"✅ Downloaded: {url}")
except Exception as e:
print(f"❌ Failed: {url} - {e}")
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ⚠️ Disclaimer
This tool is for educational purposes only. Make sure you have the right to download and use the content. Respect Twitter's Terms of Service and content creators' rights.
## 🙏 Acknowledgments
- Inspired by [yt-dlp](https://github.com/yt-dlp/yt-dlp)
- Thanks to all contributors
## 📧 Contact
- GitHub: [@w3Abhishek](https://github.com/w3Abhishek)
- Issues: [GitHub Issues](https://github.com/w3Abhishek/x-spaces-dl/issues)
---
Made with ❤️ by [w3Abhishek](https://github.com/w3Abhishek)
Raw data
{
"_id": null,
"home_page": "https://github.com/w3Abhishek/x-spaces-dl",
"name": "x-spaces-dl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "twitter, x, spaces, download, audio, recording, cli",
"author": "pyvrma",
"author_email": "pyvrma <insightfulverma@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/45/3e/e6b4379bf90099db9006d1e11b3e53e6ed04ba5baaeb4ed1bacd9c43075d/x_spaces_dl-1.0.8.tar.gz",
"platform": null,
"description": "# x-spaces-dl\r\n\r\n> A powerful command-line tool and Python library for downloading Twitter/X Spaces recordings\r\n\r\n[](https://badge.fury.io/py/x-spaces-dl)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n## \u2728 Features\r\n\r\n- \ud83c\udf99\ufe0f Download Twitter/X Spaces recordings (replays)\r\n- \ud83d\udce6 Batch download multiple spaces from a file\r\n- \ud83c\udfb5 Multiple output formats (M4A, MP3, AAC, WAV)\r\n- \ud83d\udcca Rich metadata embedding (title, host, date, participants)\r\n- \ud83d\udd04 Resume interrupted downloads\r\n- \ud83d\ude80 Fast downloads with ffmpeg or pure Python fallback\r\n- \ud83d\udd10 Guest mode (no login) with automatic fallback to authenticated mode\r\n- \ud83d\udcc8 Beautiful progress bars and detailed logging\r\n- \u2699\ufe0f Highly configurable via CLI or config file\r\n- \ud83d\udc0d Use as a library in your Python projects\r\n\r\n## \ud83d\udce5 Installation\r\n\r\n### From PyPI (recommended)\r\n\r\n```bash\r\npip install x-spaces-dl\r\n```\r\n\r\n### From source\r\n\r\n```bash\r\ngit clone https://github.com/w3Abhishek/x-spaces-dl.git\r\ncd x-spaces-dl\r\npip install -e .\r\n```\r\n\r\n### Optional: Install ffmpeg for faster downloads\r\n\r\n- **Ubuntu/Debian**: `sudo apt install ffmpeg`\r\n- **macOS**: `brew install ffmpeg`\r\n- **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Command Line\r\n\r\n```bash\r\n# Download a space (guest mode)\r\nx-spaces-dl https://x.com/i/spaces/1234567890\r\n\r\n# Download with authentication (if guest mode fails)\r\nx-spaces-dl https://x.com/i/spaces/1234567890 --cookies cookies.txt\r\n\r\n# Download multiple spaces from a file\r\nx-spaces-dl --batch urls.txt\r\n\r\n# Download as MP3 with metadata\r\nx-spaces-dl https://x.com/i/spaces/1234567890 --format mp3 --embed-metadata\r\n\r\n# Custom output filename\r\nx-spaces-dl https://x.com/i/spaces/1234567890 -o \"my_space.m4a\"\r\n\r\n# Show space info without downloading\r\nx-spaces-dl https://x.com/i/spaces/1234567890 --info-only\r\n```\r\n\r\n### Python Library\r\n\r\n```python\r\nfrom xspacesdl import XSpacesDL\r\n\r\n# Initialize downloader\r\ndownloader = XSpacesDL()\r\n\r\n# Download a space\r\ndownloader.download_space(\r\n \"https://x.com/i/spaces/1234567890\",\r\n output_file=\"space.m4a\"\r\n)\r\n\r\n# Get space metadata\r\nmetadata = downloader.get_space_metadata(\"https://x.com/i/spaces/1234567890\")\r\nprint(f\"Title: {metadata['title']}\")\r\nprint(f\"Host: {metadata['host']}\")\r\n```\r\n\r\n## \ud83d\udcd6 Usage\r\n\r\n### Basic Commands\r\n\r\n```bash\r\n# Download with default settings\r\nx-spaces-dl <SPACE_URL>\r\n\r\n# Specify output file\r\nx-spaces-dl <SPACE_URL> -o output.m4a\r\n\r\n# Use authenticated mode with cookies\r\nx-spaces-dl <SPACE_URL> --cookies cookies.txt\r\n\r\n# Force guest mode (no fallback)\r\nx-spaces-dl <SPACE_URL> --guest-only\r\n```\r\n\r\n### Batch Download\r\n\r\nCreate a text file with one URL per line:\r\n\r\n```text\r\nhttps://x.com/i/spaces/1234567890\r\nhttps://x.com/i/spaces/0987654321\r\nhttps://x.com/i/spaces/1111111111\r\n```\r\n\r\nThen run:\r\n\r\n```bash\r\nx-spaces-dl --batch urls.txt\r\n```\r\n\r\n### Output Formats\r\n\r\n```bash\r\n# Convert to MP3\r\nx-spaces-dl <SPACE_URL> --format mp3\r\n\r\n# Convert to WAV\r\nx-spaces-dl <SPACE_URL> --format wav\r\n\r\n# Keep original M4A\r\nx-spaces-dl <SPACE_URL> --format m4a\r\n```\r\n\r\n### Metadata\r\n\r\n```bash\r\n# Embed metadata (title, host, date)\r\nx-spaces-dl <SPACE_URL> --embed-metadata\r\n\r\n# Save metadata to JSON\r\nx-spaces-dl <SPACE_URL> --save-metadata\r\n\r\n# Show info only (no download)\r\nx-spaces-dl <SPACE_URL> --info-only\r\n```\r\n\r\n### Advanced Options\r\n\r\n```bash\r\n# Custom output directory\r\nx-spaces-dl <SPACE_URL> --output-dir ~/Downloads/Spaces\r\n\r\n# Filename template\r\nx-spaces-dl <SPACE_URL> --template \"{date}_{host}_{title}\"\r\n\r\n# Retry failed downloads\r\nx-spaces-dl <SPACE_URL> --retry 3\r\n\r\n# Quiet mode (no output)\r\nx-spaces-dl <SPACE_URL> --quiet\r\n\r\n# Verbose mode (detailed logging)\r\nx-spaces-dl <SPACE_URL> --verbose\r\n\r\n# Dry run (show what would be downloaded)\r\nx-spaces-dl <SPACE_URL> --dry-run\r\n```\r\n\r\n### Configuration File\r\n\r\nCreate `~/.config/xspacesdl/config.yaml`:\r\n\r\n```yaml\r\noutput_dir: ~/Downloads/Spaces\r\nformat: mp3\r\nembed_metadata: true\r\ncookies_file: ~/cookies.txt\r\nretry_attempts: 3\r\ntemplate: \"{date}_{host}_{title}\"\r\n```\r\n\r\nThen simply run:\r\n\r\n```bash\r\nx-spaces-dl <SPACE_URL>\r\n```\r\n\r\n## \ud83d\udd10 Authentication\r\n\r\nFor private spaces or when guest mode fails:\r\n\r\n1. **Export cookies from your browser**:\r\n - Install a browser extension like \"Get cookies.txt\" or \"EditThisCookie\"\r\n - Visit twitter.com/x.com and login\r\n - Export cookies to `cookies.txt` (Netscape format)\r\n\r\n2. **Use cookies with x-spaces-dl**:\r\n ```bash\r\n x-spaces-dl <SPACE_URL> --cookies cookies.txt\r\n ```\r\n\r\n## \ud83d\udee0\ufe0f All CLI Options\r\n\r\n```\r\nx-spaces-dl [OPTIONS] [SPACE_URL]\r\n\r\nOptions:\r\n -o, --output TEXT Output filename\r\n -d, --output-dir PATH Output directory\r\n -b, --batch FILE Batch download from file\r\n -f, --format [m4a|mp3|aac|wav] Output format (default: m4a)\r\n -c, --cookies FILE Path to cookies.txt file\r\n --guest-only Use guest mode only (no auth fallback)\r\n --embed-metadata Embed metadata into audio file\r\n --save-metadata Save metadata to JSON file\r\n --info-only Show space info without downloading\r\n --template TEXT Filename template\r\n --retry INTEGER Retry attempts (default: 3)\r\n --no-resume Disable resume capability\r\n -q, --quiet Quiet mode\r\n -v, --verbose Verbose mode\r\n --dry-run Dry run (no actual download)\r\n --config FILE Config file path\r\n --version Show version\r\n --help Show this message and exit\r\n```\r\n\r\n## \ud83d\udcda Python API\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom xspacesdl import XSpacesDL\r\n\r\n# Initialize\r\ndl = XSpacesDL()\r\n\r\n# Download a space\r\ndl.download_space(\"https://x.com/i/spaces/1234567890\")\r\n```\r\n\r\n### With Authentication\r\n\r\n```python\r\nfrom xspacesdl import XSpacesDL\r\n\r\n# Initialize with cookies\r\ndl = XSpacesDL(cookies_file=\"cookies.txt\")\r\n\r\n# Download\r\ndl.download_space(\"https://x.com/i/spaces/1234567890\")\r\n```\r\n\r\n### Advanced Usage\r\n\r\n```python\r\nfrom xspacesdl import XSpacesDL\r\nfrom xspacesdl.config import Config\r\n\r\n# Custom configuration\r\nconfig = Config(\r\n output_dir=\"./downloads\",\r\n format=\"mp3\",\r\n embed_metadata=True,\r\n retry_attempts=5\r\n)\r\n\r\n# Initialize with config\r\ndl = XSpacesDL(config=config)\r\n\r\n# Get metadata\r\nmetadata = dl.get_space_metadata(\"https://x.com/i/spaces/1234567890\")\r\n\r\n# Download with custom options\r\ndl.download_space(\r\n \"https://x.com/i/spaces/1234567890\",\r\n output_file=\"custom_name.mp3\",\r\n format=\"mp3\"\r\n)\r\n```\r\n\r\n### Batch Download\r\n\r\n```python\r\nfrom xspacesdl import XSpacesDL\r\n\r\ndl = XSpacesDL()\r\n\r\nurls = [\r\n \"https://x.com/i/spaces/1234567890\",\r\n \"https://x.com/i/spaces/0987654321\",\r\n]\r\n\r\nfor url in urls:\r\n try:\r\n dl.download_space(url)\r\n print(f\"\u2705 Downloaded: {url}\")\r\n except Exception as e:\r\n print(f\"\u274c Failed: {url} - {e}\")\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\r\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\r\n4. Push to the branch (`git push origin feature/AmazingFeature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcdd License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \u26a0\ufe0f Disclaimer\r\n\r\nThis tool is for educational purposes only. Make sure you have the right to download and use the content. Respect Twitter's Terms of Service and content creators' rights.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Inspired by [yt-dlp](https://github.com/yt-dlp/yt-dlp)\r\n- Thanks to all contributors\r\n\r\n## \ud83d\udce7 Contact\r\n\r\n- GitHub: [@w3Abhishek](https://github.com/w3Abhishek)\r\n- Issues: [GitHub Issues](https://github.com/w3Abhishek/x-spaces-dl/issues)\r\n\r\n---\r\n\r\nMade with \u2764\ufe0f by [w3Abhishek](https://github.com/w3Abhishek)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful command-line tool and Python library for downloading Twitter/X Spaces recordings",
"version": "1.0.8",
"project_urls": {
"Documentation": "https://github.com/w3Abhishek/x-spaces-dl#readme",
"Homepage": "https://github.com/w3Abhishek/x-spaces-dl",
"Issues": "https://github.com/w3Abhishek/x-spaces-dl/issues",
"Repository": "https://github.com/w3Abhishek/x-spaces-dl"
},
"split_keywords": [
"twitter",
" x",
" spaces",
" download",
" audio",
" recording",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0b063918cdb1c1451398e503c4a81a92fbec3ae172ab726eda35e500406fb001",
"md5": "a1cc7202dcc1c2e37ec9971e5d0b8e9c",
"sha256": "e0ddd6ee1a0b274bf1d8bf6a2da93f75f3529f93a518ab919bee6cc98f052c26"
},
"downloads": -1,
"filename": "x_spaces_dl-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1cc7202dcc1c2e37ec9971e5d0b8e9c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24196,
"upload_time": "2025-10-18T10:18:28",
"upload_time_iso_8601": "2025-10-18T10:18:28.402139Z",
"url": "https://files.pythonhosted.org/packages/0b/06/3918cdb1c1451398e503c4a81a92fbec3ae172ab726eda35e500406fb001/x_spaces_dl-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "453ee6b4379bf90099db9006d1e11b3e53e6ed04ba5baaeb4ed1bacd9c43075d",
"md5": "4fe7b219c7abfd546b1e718ecce22606",
"sha256": "1f856331a33829eef6a15161493bc12ca3d2b5d7403a49e27f75cc3c85608517"
},
"downloads": -1,
"filename": "x_spaces_dl-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "4fe7b219c7abfd546b1e718ecce22606",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 24159,
"upload_time": "2025-10-18T10:18:29",
"upload_time_iso_8601": "2025-10-18T10:18:29.699161Z",
"url": "https://files.pythonhosted.org/packages/45/3e/e6b4379bf90099db9006d1e11b3e53e6ed04ba5baaeb4ed1bacd9c43075d/x_spaces_dl-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 10:18:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "w3Abhishek",
"github_project": "x-spaces-dl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "x-spaces-dl"
}
JSON
