xdl-node

xdl-node is a TypeScript library for interacting with Twitter’s unofficial APIs—specifically for working with Twitter Spaces. This library is based on the Twspace-dl library by HoloArchivists and has been completely rewritten in TypeScript for improved type safety and maintainability.

Features

• Twitter API Clients:
  Interact with Twitter’s GraphQL, Fleets, and Live Video Stream endpoints.

• Space Metadata:
  Retrieve detailed metadata about Twitter Spaces.

• Space Downloading:
  Download Twitter Space audio streams via ffmpeg, with support for embedding cover images (e.g., user avatars).

• Live Recording:
  Record live Twitter Spaces with the ability to stop the recording gracefully.

• TypeScript Support:
  Fully typed with TypeScript, including declaration files for an improved developer experience.

Installation

Install the library via npm:

npm install xdl-node

Or with yarn:

yarn add xdl-node

Usage Guide

This guide provides examples on how to initialize the API, download a Twitter Space, and record a live Space.

1. Importing the Library

The library exports several modules:

• API: An instance of the TwitterAPI class for initializing and accessing various Twitter endpoints.
• loadCookies: A helper function to load cookies from a file (in Netscape format).
• Twspace: A class representing a Twitter Space.
• TwspaceDL: A class for downloading and processing Twitter Spaces.

2. Initializing the API

Before using any API endpoints, you need to load your cookies and initialize the API clients. Your cookies file must be in Netscape format.

import { API, loadCookies } from 'xdl-node';

// Load cookies from a file
const cookies = loadCookies('path/to/cookies.txt');

// Initialize the API clients with your cookies
API.initApis(cookies);

3. Downloading a Twitter Space

Below is an example of how to download a Twitter Space:

import { API, Twspace, TwspaceDL } from 'xdl-node';

async function downloadSpace() {
  try {
    // Create a Twspace instance from a Twitter Space URL.
    // Example URL: "https://x.com/i/spaces/SPACE_ID"
    const spaceUrl = 'https://x.com/i/spaces/SPACE_ID';
    const space = await Twspace.fromSpaceUrl(spaceUrl, API);
    console.log("Retrieved space metadata:", space);

    // Create a downloader instance with a desired filename format.
    const downloader = new TwspaceDL(space, "(%(creator_name)s)%(title)s-%(id)s");

    // Download the space audio using ffmpeg.
    await downloader.download();

    // Optionally, embed the user's profile image as cover art.
    await downloader.embedCover();

    // Clean up any temporary files created during download.
    await downloader.cleanup();

    console.log("Download complete!");
  } catch (error) {
    console.error("Error during download:", error);
  }
}

downloadSpace();

4. Live Recording a Twitter Space

To record a live Twitter Space, use the live recording functionality. The recording will continue until you explicitly stop it.

import { API, loadCookies, Twspace, TwspaceDL } from 'xdl-node';

async function recordLiveSpace() {
  try {
    // Load cookies and initialize API endpoints.
    const cookies = loadCookies('path/to/cookies.txt');
    API.initApis(cookies);

    // Create a Twspace instance from a user's profile URL.
    // This example attempts to detect a live space from the user's account.
    const userUrl = 'https://x.com/username';
    const space = await Twspace.fromUserAvatar(userUrl, API);

    // Create a downloader instance.
    const downloader = new TwspaceDL(space);

    // Start live recording; the recording will run until you stop it.
    await downloader.startLiveRecording();
    console.log("Live recording started. Use downloader.stopLiveRecording() to stop.");

    // To stop live recording, you can later call:
    // downloader.stopLiveRecording();
  } catch (error) {
    console.error("Error during live recording:", error);
  }
}

recordLiveSpace();

API Overview

TwitterAPI

Aggregates clients for different Twitter endpoints:

• graphql_api for GraphQL queries.
• fleets_api for Fleets endpoints.
• live_video_stream_api for live video stream endpoints.

Initialization:
Call API.initApis(cookies) to initialize these clients.

Twspace

Represents a Twitter Space and provides static methods:

• fromSpaceUrl(url, apiInstance): Creates a Twspace instance from a Space URL.
• fromUserAvatar(user_url, apiInstance): Creates a Twspace instance from a user’s profile URL (to detect live spaces).
• fromFile(filePath): Creates a Twspace instance from a local metadata file.

TwspaceDL

Manages downloading and processing of Twitter Space audio.

• download(): Downloads the audio stream via ffmpeg.
• embedCover(): Embeds a cover image (such as a user’s avatar) into the audio file.
• startLiveRecording(): Begins live recording of a Twitter Space.
• stopLiveRecording(): Stops an ongoing live recording.
• cleanup(): Removes temporary files created during the download process.

Contributing

Contributions are welcome! For collaboration or if you have any ideas or issues, please contact t.me/norilover.

License

This project is licensed under the MIT License.