Skip to main content

​
Welcome Contributors!

We welcome contributions from the community! Whether you’re fixing bugs, adding features, improving documentation, or helping with translations, your contributions make LoFi Engine better for everyone.
Before contributing, please read through these guidelines to ensure a smooth collaboration process.

​
Ways to Contribute

Bug Reports

Report issues you encounter while using the app

Feature Requests

Suggest new features or improvements

Code Contributions

Fix bugs or implement new features

Documentation

Improve or translate documentation

Design

Contribute artwork or UI improvements

Testing

Test new features and provide feedback

​
Getting Started

Before you start contributing:
1

Check the issue tracker

Visit the issue tracker to:
  • Find issues labeled good first issue for beginners
  • See what’s already being worked on
  • Discuss new ideas before implementing
2

Set up your development environment

Follow the Development Setup guide to get LoFi Engine running locally.
3

Understand the architecture

Read the System Architecture documentation to understand how the project is structured.

​
Contribution Workflow

Follow this workflow to contribute code changes:
1

Fork the repository

Create your own fork of the repository:
  1. Go to github.com/meel-hd/lofi-engine
  2. Click the “Fork” button in the top-right
  3. Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/lofi-engine
cd lofi-engine
2

Create a new branch

Create a branch for your feature or bugfix:
git checkout -b feature/your-feature-name
Branch naming conventions:
  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Adding tests
Examples:
git checkout -b feature/add-bass-synth
git checkout -b fix/audio-glitch-on-pause
git checkout -b docs/improve-setup-guide
3

Implement and test your changes

Make your changes and test them thoroughly:
# Run the development server
pnpm tauri:d

# Run type checking
pnpm check
Always test your changes across different platforms if possible (Linux, macOS, Windows).
4

Commit your changes

Make clear, descriptive commits:
git add .
git commit -m "feat: add bass synthesizer to music engine"
Commit message format:
  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation
  • style: - Formatting changes
  • refactor: - Code restructuring
  • test: - Adding tests
  • chore: - Maintenance tasks
5

Push to your fork

Push your changes to your GitHub fork:
git push origin feature/your-feature-name
6

Open a Pull Request

  1. Go to your fork on GitHub
  2. Click “Pull Request” → “New Pull Request”
  3. Select the master branch as the base
  4. Select your feature branch as the compare
  5. Fill in the PR template with:
    • Description of changes
    • Related issue numbers
    • Testing performed
    • Screenshots (if UI changes)

​
Code Style Guidelines

​
TypeScript / JavaScript

// Use descriptive variable names
const chordProgression = ChordProgression.generate(8);

// Add comments for complex logic
// Normalize intervals to single octave for mode generation
const mode = intervals.map(n => n >= 12 ? n - 12 : n);

// Use TypeScript types
interface AudioEffect {
  type: 'filter' | 'reverb' | 'delay';
  value: number;
}

​
Svelte Components

<script lang="ts">
  // Group imports: external first, then internal
  import * as Tone from 'tone';
  import Piano from '$lib/engine/Piano/Piano';
  
  // Use TypeScript for props
  export let volume: number = 0.8;
  export let enabled: boolean = false;
  
  // Document complex reactive statements
  // Recalculate frequency when volume changes
  $: frequency = volume * 1000;
</script>

<style>
  /* Use clear class names */
  .piano-control {
    padding: 1rem;
    background: var(--bg-color);
  }
</style>

​
Rust (Tauri Backend)

// Use idiomatic Rust
use tauri::command;

#[command]
fn process_audio(samples: Vec<f32>) -> Result<Vec<f32>, String> {
    // Add error handling
    if samples.is_empty() {
        return Err("No samples provided".to_string());
    }
    
    Ok(samples)
}

​
Pull Request Guidelines

​
Before Submitting

Ensure your PR meets these criteria:
  • Code follows project style guidelines
  • All type checks pass (pnpm check)
  • Changes have been tested locally
  • Commit messages are clear and descriptive
  • PR description explains what and why
  • Related issues are referenced
  • No console errors or warnings
  • New features include comments/documentation

​
PR Template

When opening a PR, include: 
## Description
Brief description of what this PR does.

## Related Issues
Fixes #123
Related to #456

## Changes Made
- Added bass synthesizer to music engine
- Updated audio processing pipeline
- Added tests for new synth

## Testing
- [x] Tested on Linux
- [x] Tested on macOS
- [ ] Tested on Windows

## Screenshots
(If applicable)

## Additional Notes
Any other context or considerations.

​
Music Generation Contributions

Contributing to the procedural music system:
To modify chord progression logic:
  1. Edit src/lib/engine/Chords/Chords.ts
  2. Update nextChordIdxs arrays with valid progressions
  3. Test that progressions sound musical
  4. Document music theory reasoning
Example:
const I = new Chord(
    1,
    [0,4,7,11,14,17,21],
    toChordIdxs([2,3,4,5,6,7])  // Allow progression to ii-vii
);
To add new audio effects:
  1. Use Tone.js effect nodes
  2. Chain effects properly
  3. Add user controls in UI
  4. Document effect parameters
Example:
const reverb = new Tone.Reverb(2.0);
const delay = new Tone.FeedbackDelay("8n", 0.5);
sampler.chain(reverb, delay, Tone.Master);
To add new instruments:
  1. Create new directory in src/lib/engine/
  2. Implement sampler class with effects
  3. Add samples to public/assets/engine/
  4. Integrate with main audio engine
  5. Add UI controls
See: src/lib/engine/Piano/Piano.ts:1 for reference

​
Reporting Bugs

Found a bug? Help us fix it:
1

Search existing issues

Check if the bug has already been reported:LoFi Engine Issues
2

Create a new issue

If it’s a new bug, create a detailed report:Include:
  • Clear description of the bug
  • Steps to reproduce
  • Expected vs actual behavior
  • Platform (Linux/macOS/Windows)
  • App version
  • Screenshots or videos (if applicable)
  • Console errors (if any)
3

Label appropriately

Use labels to categorize:
  • bug - Something isn’t working
  • critical - App crashes or data loss
  • audio - Audio-related issues
  • ui - User interface problems
  • performance - Slow or laggy behavior

​
Requesting Features

Have an idea for LoFi Engine?
1

Check existing requests

Search issues labeled enhancement to see if it’s already requested.
2

Create a feature request

Open a new issue with:
  • Clear description of the feature
  • Use case / problem it solves
  • Proposed implementation (if you have ideas)
  • Mockups or examples (if applicable)
3

Discuss with maintainers

Engage in discussion to refine the idea before implementing.

​
Community Guidelines

Be Respectful

Treat all contributors with respect and kindness

Be Patient

Maintainers are volunteers—reviews take time

Be Open

Accept feedback gracefully and iterate

Be Helpful

Help other contributors when you can

​
Recognition

All contributors are recognized in:
  • GitHub contributors list
  • Release notes for significant contributions
  • The app’s “About” section

​
Getting Help

Need help contributing?

Issue Tracker

Ask questions or report problems

Development Setup

Get your environment set up

Architecture Guide

Understand the codebase

Music Generation

Learn about the audio engine

​
License

By contributing to LoFi Engine, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to LoFi Engine! Your efforts help create a better experience for everyone in the community.

Build docs developers (and LLMs) love

Get started for freeTalk to us