mirror of
https://github.com/Dasemu/x-space-downloader.git
synced 2026-10-14 05:59:48 +00:00
ef3492ac99
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
163 lines
3.6 KiB
Markdown
163 lines
3.6 KiB
Markdown
# 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:
|
|
```bash
|
|
# macOS
|
|
brew install ffmpeg
|
|
|
|
# Ubuntu/Debian
|
|
sudo apt install ffmpeg
|
|
|
|
# Windows
|
|
# Download from https://ffmpeg.org/download.html
|
|
```
|
|
|
|
### Install the tool
|
|
|
|
```bash
|
|
git clone https://github.com/synapz-org/x-space-downloader.git
|
|
cd x-space-downloader
|
|
pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic usage
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
x-space-dl --cookies cookies.txt https://x.com/i/spaces/1ZkKzZWnVRRKv
|
|
```
|
|
|
|
### Specify output directory
|
|
|
|
```bash
|
|
x-space-dl --output ~/Downloads https://x.com/i/spaces/1ZkKzZWnVRRKv
|
|
```
|
|
|
|
### Full options
|
|
|
|
```bash
|
|
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](https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
|
|
- Firefox: [cookies.txt](https://addons.mozilla.org/en-US/firefox/addon/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
|
|
|
|
```bash
|
|
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](https://github.com/yt-dlp/yt-dlp) - Media downloader
|
|
- [Click](https://click.palletsprojects.com/) - CLI framework
|