Orpheus Engine

Orpheus Engine is a comprehensive Digital Audio Workstation (DAW) ecosystem built with React, TypeScript, Python, and Electron. This repository contains the complete Orpheus Engine with integrated frontend workstation, backend services, AI/ML capabilities, and professional audio processing tools.

🆕 What's New in v1.0.10

Recent Features & Improvements

✅ Complete Electron Integration: Native desktop application with full system integration
✅ Enhanced UI Components: Professional DAW interface with Ableton -inspired design
✅ Advanced Testing Suite: Comprehensive test coverage with visual regression testing
✅ TypeScript Compliance: 100% TypeScript compliance with zero compilation errors
✅ Alias System: Improved import path resolution with @orpheus/* aliases
✅ Test Infrastructure: Fixed import path issues and comprehensive Lane component testing

Recent Bug Fixes

Fixed Vite server startup failure by adding missing @vitejs/plugin-react dependency
Fixed directory path in start-electron.sh script that was causing navigation errors
Fixed WindowAutoScroll component TypeScript errors and scroll direction bugs
Fixed import path alias resolution in test files
Resolved ipcRenderer errors in WorkstationProvider

✨ Features

🎛️ Professional DAW Interface: Modern workstation UI with timeline, track management, and mixer
🎵 Audio Processing: Real-time audio clip management and editing capabilities
🖥️ Electron Desktop App: Native desktop experience with system integration
⚡ Fast Development: Vite-powered development with hot module replacement
🧪 Comprehensive Testing: Well-tested components with visual regression testing
📊 Advanced UI Components: Resizable panels, drag-and-drop, and professional controls
🎨 Modern Styling: FL Studio-inspired design with dark theme and professional aesthetics
🔧 TypeScript: Full type safety with zero compilation errors

🚀 Quick Start

Prerequisites

Node.js v20.11.1+ (as specified in package.json engines)
pnpm v10.6.4+ (required package manager)
Python 3.8+ (for AI/ML backend services)
Git (for version control)

1. Clone and Setup

# Clone the repository
git clone https://github.com/jhead12/orpheus-engine.git
cd orpheus-engine

# Install all dependencies and setup the project
pnpm run setup

# Or install dependencies manually
pnpm install

# Make shell scripts executable (if needed on Unix systems)
chmod +x scripts/*.sh

2. Start the Application

# Start in development mode (Electron + Vite)
pnpm run dev

# Or start Vite dev server only
pnpm run dev:vite

# For local development with custom port
pnpm run dev:local

The application will be available at:

Development Server: http://localhost:5173 (Vite)
Local Development: http://localhost:3000 (custom port)
Electron Desktop App: Launches automatically with pnpm run dev

3. Web Demo & Jupyter Integration

# Start the interactive web demo (Jupyter notebook)
pnpm run demo

# Or run Jupyter Lab directly
pnpm run demo:lab

# Or run Jupyter Notebook directly  
pnpm run demo:notebook

# Install Python dependencies if needed
pip install -r requirements.txt

The Orpheus Web Demo is accessible from the /demo folder and provides:

🎛️ Interactive DAW component showcase
🔍 Platform capability testing (Electron, Browser, Python)
🎵 Real-time audio processing demonstrations
📊 Cross-platform compatibility testing
🧪 Component integration with existing Jupyter backend
🤖 HP AI Studio integration for ML-powered audio analysis

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Setup & Installation - Requirements, MLflow setup, macOS fixes
Architecture & Design - System architecture and plugin development
Audio Production - Professional audio setup and hardware compatibility
Competition Info - Information for HP AI Studio competition judges

📖 Quick Links:

Full Documentation Index - Complete navigation hub
Project Requirements - Dependencies and setup requirements
MLflow Integration - HP AI Studio configuration

4. Build for Production

# Build the application
npm run build

# Preview the build
npm run preview

🔧 Available Commands

Development & Testing

npm run dev - Start development mode with Electron
npm run dev:vite - Start Vite development server only
npm run dev:local - Start with local configuration
npm run dev:prod - Start in production mode
npm run dev:headless - Start in headless mode for CI/CD
npm start - Start the application
npm run preview - Preview the built application

Building & Packaging

npm run build - Build the application and create Electron package
npm test - Run all tests
npm run test:watch - Run tests in watch mode
npm run test:ui - Run tests with UI
npm run lint - Run ESLint

Visual Testing

npm run test:screenshots - Run visual regression tests
npm run test:visual - Run visual tests
npm run test:visual:update - Update visual test snapshots
npm run test:visual:gif - Run GIF-based visual tests
npm run list:screenshots - List all screenshot tests

Development Tools

npm run setup:electron - Setup Electron symlinks
npm run setup:aliases - Setup import aliases
npm run fix-vite - Fix Vite dependencies
npm run fix-electron-path - Fix Electron path issues
npm run refactor:imports - Refactor import statements
npm run find-large-files - Find large files in the project

📁 Project Structure

orpheus-engine/
├── 📄 package.json              # Project configuration and scripts
├── 📄 README.md                 # This documentation
├── 📄 CHANGELOG.md              # Version history and changes
├── 📄 vite.config.ts           # Vite configuration
├── 📄 vitest.config.ts         # Test configuration
├── 📄 tsconfig.json            # TypeScript configuration
├── 📄 electron-launch.js       # Electron launcher
│
├── 🖥️  electron/               # Electron main process
│   ├── main.ts                 # Main application entry
│   ├── preload.ts             # Renderer preload scripts
│   └── tsconfig.json          # Electron TypeScript config
│
├── 📜 scripts/                 # Development and build scripts
│   ├── setup-electron-symlinks.sh
│   ├── fix-electron-path.js
│   ├── refactor-imports.js
│   └── visual-agent.js
│
├── 📁 src/                     # Source code
│   ├── App.tsx                # Main React application
│   ├── index.css             # Global styles
│   ├── components/           # Reusable UI components
│   ├── contexts/            # React contexts
│   ├── screens/             # Application screens
│   │   └── workstation/     # DAW workstation interface
│   ├── services/            # Service utilities
│   └── types/               # TypeScript type definitions
│
├── 📸 __snapshots__/           # Visual test snapshots
│   ├── screenshots/
│   ├── diffs/
│   └── gifs/
│
└── 🎨 assets/                  # Static assets
    └── screenshots/

Key Components

🎛️ Workstation Interface: Professional DAW UI with timeline, tracks, and mixer
🧩 Component Library: Reusable UI components with comprehensive tests
⚡ Electron Integration: Native desktop features and system integration
🎵 Audio Engine: Real-time audio clip management and processing
🌐 Service Architecture: Modular services for audio, UI, and data management
🔧 Development Tools: Comprehensive scripts for development and maintenance

🔧 Development Workflow

Code Organization

This repository focuses on the frontend workstation interface of Orpheus Engine:

Frontend Workstation/
├── src/screens/workstation/    # Main DAW interface
├── src/components/            # Reusable UI components  
├── src/contexts/             # React context providers
├── src/services/             # Utility services
└── src/types/               # TypeScript definitions

Hot Reloading

Frontend: Vite provides fast hot module replacement (HMR)
Electron: Nodemon watches for changes and restarts
Tests: Vitest runs in watch mode for continuous testing

Building for Production

Build the application:

npm run build

Run tests and linting:

npm test && npm run lint

Package for distribution:

npm run build  # Creates packaged app in dist/

Architecture Notes

Frontend:
- Electron for native desktop features
- React for UI components with hooks and context
- TypeScript for type safety and better DX
- Vite for fast development and building
Testing:
- Vitest for unit and integration tests
- Visual regression testing with screenshots
- Comprehensive component test coverage
- Import alias resolution for clean test structure
Development Experience:
- Hot module replacement for instant feedback
- TypeScript integration with zero compilation errors
- ESLint for code quality and consistency
- Automated visual testing for UI regression detection

🌐 Integration with Main Orpheus Engine

This workstation frontend integrates with the larger Orpheus Engine ecosystem:

Main Repository Features

🤖 AI/RAG Backend: Python-powered audio analysis and intelligent assistance
🎵 Audio Processing Backend: Node.js/TypeScript audio engine (port 7008)
📊 Monitoring Backend: System monitoring and health checks (port 8000)
🔗 Blockchain Integration: IPFS and Story Protocol support
🐍 Python Services: ML/AI processing and audio feature extraction

Environment Configuration

For full-stack development, you can configure backend services:

# Example environment variables for integration
BACKEND_HOST=localhost
BACKEND_PORT=5001
AUDIO_HOST=localhost  
AUDIO_PORT=7008
MONITOR_HOST=localhost
MONITOR_PORT=8000

🧩 Plugin System

The workstation supports an extensible plugin architecture:

Built-in Features

Audio Export Plugins: WAV, MP3, FLAC export capabilities
UI Components: Extensible component library
Context Providers: Modular state management
Service Integration: Backend service connectors

Extending Functionality

// Example: Adding new audio export plugin
import { ExportPlugin } from '@orpheus/types/plugins';

const customExportPlugin: ExportPlugin = {
  name: 'CustomFormat',
  export: async (audioData, options) => {
    // Custom export logic
  }
};

🔧 Troubleshooting

Common Issues & Solutions

Vite Server Issues:
```
npm run fix-vite
```
Electron Path Issues:
```
npm run fix-electron-path
```

Import/Alias Issues:

npm run setup:aliases
npm run refactor:imports

Test Failures:

# Update visual test snapshots
npm run test:visual:update

# Check test output
npm run test:ui

Build Issues:

# Clean and rebuild
rm -rf node_modules dist
npm install
npm run build

Getting Help

Check the main repository for full ecosystem documentation
Run comprehensive diagnostics: npm run validate:env
Review the CHANGELOG.md for recent changes and fixes
Check GitHub issues for known problems and solutions

TODO Items from Main Repository

Based on the main Orpheus Engine repository, here are key features and improvements to implement:

High Priority

Medium Priority

Test Infrastructure: Fixed import path issues and comprehensive Lane component testing ✅
Vite Development Server: Fixed server startup issues and added missing dependencies ✅
Directory Navigation: Fixed path issues in startup scripts ✅
WindowAutoScroll Component: Fixed TypeScript errors and scroll direction bugs ✅
Server-Agnostic Configuration: Add environment-based configuration system
Performance Optimization: Improve performance with large numbers of tracks
Automation Lanes: Implement automation curve editing and playback
Effects Processing: Add built-in effects and plugin support
Advanced Timeline: Implement snap-to-grid, loop regions, and markers

Low Priority

Blockchain Integration: Add IPFS and Story Protocol support for decentralized features
Advanced AI Features: Integrate ML-powered audio analysis and suggestions
Cloud Storage: Add cloud storage and collaboration features
Mobile Responsive: Make interface work on tablets and mobile devices
Accessibility: Improve accessibility for users with disabilities

Development Infrastructure

Comprehensive Build System: Working Electron + Vite development environment ✅
Hot Module Replacement: Fast development with automatic reloading ✅
Visual Regression Testing: Screenshot-based UI testing system ✅
Monorepo Integration: Align with main repository structure and workspace management
Advanced Testing: Add E2E testing with Playwright for full user workflows
CI/CD Pipeline: Set up automated testing, building, and deployment
Documentation: Add comprehensive API documentation and user guides
Performance Monitoring: Add performance tracking and optimization tools

HP AI Studio Competition Requirements

Recently Completed (v1.0.10)

✅ Fixed Vite server startup by adding missing @vitejs/plugin-react dependency
✅ Fixed directory path in start-electron.sh script that was causing navigation errors
✅ Fixed WindowAutoScroll component TypeScript errors and scroll direction bugs
✅ Fixed import path alias resolution in test files
✅ Resolved ipcRenderer errors in WorkstationProvider
✅ Implemented comprehensive Lane component testing with visual regression tests
✅ Achieved 100% TypeScript compliance with zero compilation errors

Current Limitations (as noted in original README)

User interface is functional, but audio processing needs implementation
Performance optimization needed for large numbers of tracks
Main functionality prioritized over performance optimization
Frontend separated from main repository due to deprecated dependency issues

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Development Process

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes with proper TypeScript types
Add/update tests as needed
Run tests: npm test
Run linting: npm run lint
Submit a pull request

License

See LICENSE for details.

System Requirements

Node.js v16+ (v18+ recommended)
npm v7+ or pnpm for package management
Modern web browser (for development)
Electron-compatible operating system (Windows, macOS, Linux)

For the full Orpheus Engine ecosystem, additional requirements include:

Python 3.8+ (for AI/ML features)
System packages: dbus-x11, xvfb (for headless operation)
Rust (for some audio processing dependencies)

Name		Name	Last commit message	Last commit date
Latest commit History 289 Commits
.github/workflows		.github/workflows
__snapshots__/screenshots		__snapshots__/screenshots
archives/workstation-backups/20250603_124545		archives/workstation-backups/20250603_124545
backups		backups
demo		demo
docs		docs
electron		electron
notebooks		notebooks
orpheus-engine		orpheus-engine
public		public
scripts		scripts
src		src
workstation		workstation
.env		.env
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.npmrc		.npmrc
.permissions-cache		.permissions-cache
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
electron-launch.mjs		electron-launch.mjs
eslint.config.js		eslint.config.js
nodemon.json		nodemon.json
package.json		package.json
package.json.new		package.json.new
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
requirements.txt		requirements.txt
setup_hp_ai_studio.py		setup_hp_ai_studio.py
tsconfig.app.json		tsconfig.app.json
tsconfig.node.json		tsconfig.node.json
tsconfig.node.tsbuildinfo		tsconfig.node.tsbuildinfo
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.d.ts		vite.config.d.ts
vite.config.js		vite.config.js
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts
vitest.models.config.ts		vitest.models.config.ts
vitest.visual.config.ts		vitest.visual.config.ts
webpack.config.js		webpack.config.js

License

jhead12/orpheus-engine

Folders and files

Latest commit

History

Repository files navigation

Orpheus Engine

🆕 What's New in v1.0.10

Recent Features & Improvements

Recent Bug Fixes

✨ Features

🚀 Quick Start

Prerequisites

1. Clone and Setup

2. Start the Application

3. Web Demo & Jupyter Integration

📚 Documentation

4. Build for Production

🔧 Available Commands

Development & Testing

Building & Packaging

Visual Testing

Development Tools

📁 Project Structure

Key Components

🔧 Development Workflow

Code Organization

Hot Reloading

Building for Production

Architecture Notes

🌐 Integration with Main Orpheus Engine

Main Repository Features

Environment Configuration

🧩 Plugin System

Built-in Features

Extending Functionality

🔧 Troubleshooting

Common Issues & Solutions

Getting Help

TODO Items from Main Repository

High Priority

Medium Priority

Low Priority

Development Infrastructure

HP AI Studio Competition Requirements

Recently Completed (v1.0.10)

Current Limitations (as noted in original README)

Contributing

Development Process

License

System Requirements

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages