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.

• ✅ 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

• 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

• 🎛️ 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

• 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)

# 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

# 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

# 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

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

# Build the application
npm run build

# Preview the build
npm run preview

• 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

• 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

• 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

• 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

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/

• 🎛️ 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

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

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

1. Build the application:

npm run build

1. Run tests and linting:

npm test && npm run lint

1. Package for distribution:

npm run build  # Creates packaged app in dist/

1. 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

2. Testing:

   • Vitest for unit and integration tests
   • Visual regression testing with screenshots
   • Comprehensive component test coverage
   • Import alias resolution for clean test structure

3. 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

This workstation frontend integrates with the larger Orpheus Engine ecosystem:

• 🤖 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

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

The workstation supports an extensible plugin architecture:

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

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

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

1. Vite Server Issues:

   npm run fix-vite

2. Electron Path Issues:

   npm run fix-electron-path

3. Import/Alias Issues:

   npm run setup:aliases
   npm run refactor:imports

4. Test Failures:

   # Update visual test snapshots
   npm run test:visual:update
   
   # Check test output
   npm run test:ui

5. Build Issues:

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

• 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

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

• 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 ✅
• MLFlow & HP AI Studio Integration: Set up MLFlow experiment tracking with Jupyter Books running in HP AI Studio Framework for advanced audio ML workflows (see MLFLOW_SETUP.md)
• Audio Backend Integration: Connect to Python RAG backend (port 5001) for AI-powered audio analysis
• Real Audio Processing: Implement actual audio file loading, playback, and processing
• Export Functionality: Add comprehensive audio export capabilities (WAV, MP3, FLAC)
• MIDI Support: Add MIDI track support and MIDI file import/export
• Plugin Architecture: Implement plugin system for extending DAW capabilities

• 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

• 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

• 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

• About Section Documentation: Use Markdown to differentiate sections in About textbox
• HP AI Studio Showcase: Document how the project showcases HP AI Studio's capabilities while addressing real-world industry challenges
• Technical Workflow Documentation: Explain the technical workflow implemented with HP AI Studio
• Challenges & Solutions: Outline the challenges addressed and solutions developed
• HP AI Studio Features: Highlight key features of HP AI Studio that were leveraged
• Lessons Learned: Describe lessons learned and best practices discovered
• Demo Video Creation: Create a ~3 minute demo video that clearly demonstrates key features highlighting HP AI Studio's capabilities
• Video Accessibility: Ensure demo video is viewable by judges
• Public Code Repository: Provide link to well-documented and organized open-source public repository
• Open Source License: Include link to Apache 2.0 or MIT open-source license
• MLFlow Model Registration: Demonstrate model registration to MLFlow for local deployment
• API Key Security: Ensure no 3rd-party API keys are embedded in code
• Dependencies Documentation: Include all dependencies and requirements
• README for Judges: Create comprehensive README with steps for judging and testing
• Model Documentation: Provide detailed explanation of models downloaded and methods used

• ✅ 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

• 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

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

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

See LICENSE for details.

• 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)