# UkuleleStudio

**Repository Path**: stillwindows7/ukulele-studio

## Basic Information

- **Project Name**: UkuleleStudio
- **Description**: 尤克里里简谱生成
- **Primary Language**: HTML
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-01
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎸 Ukulele Numbered Notation to Tab Converter

> Convert numbered musical notation to ukulele tablature with visualization

## ✨ Features

- 🎼 **Notation Parsing** - Supports standard numbered notation symbols (notes, octaves, rests, ties, bar lines)
- 🎸 **Tab Generation** - Automatically generates visual tablature, 2 bars per line
- 🎹 **Multi-Key Support** - Supports C / F / G / A common keys
- 🎵 **Audio Playback** - Web Audio API playback with real-time note highlighting
- 📝 **Example Tunes** - Built-in 5 classic examples (Twinkle Star, Happy Birthday, Two Tigers, Jasmine, Ode to Joy)
- 📱 **Responsive Design** - Perfect for mobile and desktop browsers

## 🚀 Quick Start

### Install Dependencies

```bash
npm install
```

### Start Development Server

```bash
npm run dev
```

Open `http://localhost:5173/` in your browser

### Build for Production

```bash
npm run build
```

### Preview Production Build

```bash
npm run preview
```

## 📖 Usage Guide

### Input Format

| Symbol | Description | Example |
|--------|-------------|---------|
| Basic Notes | 1 2 3 4 5 6 7 | `1 2 3` |
| Low Notes | Comma prefix | `,1 ,2 ,3` |
| High Notes | Apostrophe suffix | `1' 2' 3'` |
| Rest | 0 (no sound) | `0` |
| Tie | - (extend previous note) | `-` |
| Bar Line | | (separator) | `1 2 3 5 |` |
| Separator | Space (required) | `1 2 3 5 |` |

### Example

```
1 1 5 5 | 6 6 5 - | 4 4 3 3 | 2 2 1 -
```

## 🛠️ Tech Stack

- **Framework**: React 18 + TypeScript
- **Build Tool**: Vite
- **Styling**: Tailwind CSS
- **Audio**: Web Audio API

## 📁 Project Structure

```
src/
├── components/
│   └── TabDisplay.tsx      # Tablature display component
├── App.tsx                  # Main application component
├── main.tsx                 # Application entry point
├── types.ts                 # TypeScript type definitions
├── parser.ts                # Notation parser
├── notation.ts              # Tablature mapping logic
├── audio.ts                 # Audio player
└── examples.ts              # Example tune data
```

## 🎯 Core Features

### Notation Parsing
- Supports standard numbered notation symbols
- Automatic pitch and octave recognition
- Error tolerant handling

### Tablature Mapping
- Automatic key-based conversion
- Prioritizes lower fret positions
- Auto line breaks every 2 bars

### Audio Playback
- Web Audio API synthesis
- Triangle wave for ukulele-like tone
- ADSR envelope for optimal sound quality

## 📝 Todo

- [ ] Add tempo adjustment
- [ ] Support image export
- [ ] Add lyrics alignment
- [ ] Support custom keys
- [ ] Add chord symbols

## 📄 License

MIT

## 🤝 Contributing

Issues and Pull Requests are welcome!