🎵 DAWProject-Typescript

TypeScript/JavaScript code for working with DAWProject files — enabling DAW interoperability.

📖 About

DAWProject is an open XML-based file format designed for seamless project exchange between DAWs. It allows music producers, engineers, and developers to share full session data between different DAWs without losing important information.

The original DAWProject repository, developed by Bitwig, was written in Java (https://github.com/bitwig/dawproject). This repository provides a TypeScript/JavaScript implementation, enabling integration with web applications, Node.js environments, and other JavaScript-based projects. It is inspired by the original Java version and the Python port (DAWProject-Py).

We love the idea of DAWProject and want to see it in every DAW. The more people building on it, the better—so we're making our TypeScript version publicly available. If anyone wants to turn it into an npm package, extend it, or modify it further, feel free!

📦 Installation

Since this is currently a source-only library, you can clone the repository and use it directly in your TypeScript/JavaScript project:

git clone https://github.com/perivar/dawproject-typescript.git
cd dawproject-ts

Install dependencies using npm or yarn:

npm install
# or
yarn install

Then, import it into your TypeScript/JavaScript project:

import { DawProject, Project, Application, Track, Channel, RealParameter, Unit, ContentType, MixerRole, Utility } from 'dawproject-typescript';

(Note: Update the import path based on your project structure)

🚀 Quick Start

Loading a DAWProject file (.dawproject container)

import { DawProject, Project } from 'dawproject-typescript';
import * as fs from 'fs/promises'; // Requires Node.js fs module

async function loadExampleProject(filePath: string) {
  try {
    const fileData = await fs.readFile(filePath);
    const project: Project = await DawProject.loadProject(fileData);

    // Print project metadata
    console.log(`Project Version: ${project.version}`);
    console.log(`Application: ${project.application.name} v${project.application.version}`);
    console.log(`Tracks: ${project.structure.length}`);

  } catch (error) {
    console.error("Error loading project:", error);
  }
}

// Example usage:
// loadExampleProject("path/to/your/example.dawproject");

Creating an Empty DAWProject

import { DawProject, Project, Application, MetaData } from 'dawproject-typescript';
import * as fs from 'fs/promises'; // Requires Node.js fs module

async function createEmptyProject(filePath: string) {
  try {
    // Initialize an empty project
    const project = new Project();
    project.application = new Application("My TypeScript App", "1.0.0");

    // Create minimal metadata
    const metadata = new MetaData();
    metadata.title = "Empty Project";

    // Save the project as a .dawproject container (ZIP)
    const embeddedFiles = {}; // No embedded files for an empty project
    const zipData = await DawProject.save(project, metadata, embeddedFiles);

    await fs.writeFile(filePath, zipData);
    console.log(`Empty project saved to ${filePath}`);

  } catch (error) {
    console.error("Error creating project:", error);
  }
}

// Example usage:
// createEmptyProject("new_project.dawproject");

Creating a Project with Audio Tracks

import {
  DawProject,
  Project,
  Application,
  MetaData,
  Track,
  Channel,
  RealParameter,
  Unit,
  ContentType,
  MixerRole,
  Utility,
  Referenceable // Needed for destination reference
} from 'dawproject-typescript';
import * as fs from 'fs/promises'; // Requires Node.js fs module

async function createAudioProject(filePath: string) {
  try {
    // Reset ID counter for deterministic IDs in examples
    Referenceable.resetIdCounter();

    // Initialize a project
    const project = new Project();
    project.application = new Application("My Audio App", "1.0.0");

    // Create a master track
    const masterTrack = Utility.createTrack(
      "Master",
      new Set(), // Master track typically has no specific content type
      MixerRole.MASTER,
      1.0, // volume
      0.5  // pan (center)
    );
    project.structure.push(masterTrack);

    // Create an audio track
    const audioTrack = Utility.createTrack(
      "Lead Synth",
      new Set([ContentType.AUDIO]),
      MixerRole.REGULAR,
      0.8, // volume
      0.2  // pan (slightly left)
    );

    // Route the audio track's channel to the master track's channel
    if (audioTrack.channel && masterTrack.channel) {
        audioTrack.channel.destination = masterTrack.channel;
    } else {
        console.warn("Could not connect audio track channel to master track channel.");
    }

    // Add the track to the project structure
    project.structure.push(audioTrack);

    // Create minimal metadata
    const metadata = new MetaData();
    metadata.title = "Audio Project";

    // Save the project as a .dawproject container (ZIP)
    const embeddedFiles = {}; // No embedded files in this basic example
    const zipData = await DawProject.save(project, metadata, embeddedFiles);

    await fs.writeFile(filePath, zipData);
    console.log(`Audio project saved to ${filePath}`);

  } catch (error) {
    console.error("Error creating audio project:", error);
  }
}

// Example usage:
// createAudioProject("audio_project.dawproject");

🚀 Getting Started

To run the examples or integrate the library into your project:

1. Clone the repository:

   git clone https://github.com/perivar/dawproject-typescript.git
   cd dawproject-ts

2. Install dependencies:

   npm install
   # or
   yarn install

3. You can use ts-node to run TypeScript files directly or compile your TypeScript code to JavaScript.

🏗 Examples

An src/dawproject_examples folder is included in this repository, demonstrating how to use DAWProject-TS in real-world scenarios.

To execute an example script (e.g., createExampleProject.ts), navigate to the project directory in your terminal and run using ts-node:

npx ts-node src/dawproject_examples/createExampleProject.ts

This will typically create a .dawproject file in a designated output directory (check the example script for details).

📜 DAWProject Format

DAWProject is an open XML-based format designed to enable cross-DAW compatibility. Instead of exporting audio stems, .dawproject files allow projects to be shared across DAWs while preserving:

• 🎚 Track names, volume, and panning
• 🎛 Effects and automation data
• 🎵 MIDI and audio region placements
• 🕒 Tempo and time signature changes

For the full specification, visit DAWProject on GitHub.

🛠 Development & Contributions

We welcome contributions! If you’d like to extend DAWProject-TS, whether by improving existing functionality or turning it into an npm package, feel free to contribute!

Clone the Repository

git clone https://github.com/perivar/dawproject-typescript.git
cd dawproject-ts

Contributing

• Fork the repository
• Create a feature branch (git checkout -b feature-name)
• Implement your changes and ensure tests pass (npm test or yarn test)
• Commit your changes (git commit -m "Add feature XYZ")
• Push to GitHub (git push origin feature-name)
• Open a Pull Request 🚀

Versioning and Releasing

To create a new version of the package, update the version number in package.json, add a new version tag, and trigger the GitHub Actions workflow for releasing and publishing to npm and GitHub Packages, use the following command:

npm version patch

This command will:

1. Increment the patch version number in package.json.
2. Create a new Git commit.
3. Create a new Git tag with the name v[new_version].
4. Pushing this tag to the remote repository will trigger the GitHub Actions workflow defined in .github/workflows/publish.yml to publish the package.

The command will also make sure you have committed all your changes before publishing the package.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🌎 Stay Connected

📢 Have ideas or feedback? Open an issue or start a discussion! discussions) (Note: Link may need to be created) ⭐ Star this repo if you find it useful!

🎶 DAWProject-Typescript – Enabling DAW interoperability! 🚀