Metadata-Version: 2.4
Name: dna2oiia
Version: 0.1.0
Summary: A Python package that converts DNA sequences into 'oiia' sounds.
License-File: LICENSE
Author: Chen Hsieh
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: mp3
Provides-Extra: streamlit
Description-Content-Type: text/markdown

# DNA2oiia 🧬🎵🐱

**DNA2oiia** is a Python package that converts DNA/RNA sequences into sound using the "oiia" phonetics. It supports both command-line interface (CLI) and Python API usage, handling DNA input as either raw sequences or FASTA files with single or multiple sequences.

![DNA2Oiia Demo](demo.gif)

## 🚀 Getting started

### 📥 Installation
```bash
pip install dna2oiia
```

Or install from source:
```bash
pip install git+https://github.com/ChenHsieh/DNA2oiia.git
```

Optional extras:
```bash
pip install dna2oiia[mp3]        # MP3 export support (requires pydub)
pip install dna2oiia[streamlit]  # Streamlit web app
```

## 🛠️ CLI Usage

### Convert a DNA Sequence Directly

```bash
dna2oiia -s ATCGGATTA -o my_dna
```

### Convert an RNA Sequence

```bash
dna2oiia -s AUCGGAUUA -o my_rna
```

### Convert a FASTA File

```bash
dna2oiia -f example.fasta -o fasta_output
```

If the file contains **multiple sequences**, output files will be named with header suffixes (e.g., `fasta_output_seq1.wav`, `fasta_output_seq2.wav`).

### Pipe from stdin

```bash
echo "ATCGATCG" | dna2oiia -o piped_output
cat sequence.txt | dna2oiia --play
```

### 🎧 Play Audio Directly

```bash
dna2oiia -s ATCGGATTA --play
```

Uses `afplay` (macOS), `aplay` (Linux), or PowerShell (Windows).

### ⏩ Speed Control

```bash
dna2oiia -s ATCGATCG --speed 2.0    # Double speed
dna2oiia -s ATCGATCG --speed 0.5    # Half speed
```

### 🔁 Repeat

```bash
dna2oiia -s ATCG --repeat 4         # Repeat the audio 4 times
```

### 🧬 Reverse Complement

```bash
dna2oiia -s ATCGGATTA --reverse-complement
```

Converts to the reverse complement strand before sonification (A↔T, C↔G, U→A).

### 🎵 MP3 Output

```bash
dna2oiia -s ATCGGATTA --format mp3
```

Requires `pydub`: `pip install dna2oiia[mp3]`

### 🔥 Streaming Mode

```bash
dna2oiia -s ATCGGATTA --stream
```

Outputs audio as an in-memory stream instead of writing to disk.

## 🧑‍💻 Python API Usage

### Convert a Single Sequence
```python
from dna2oiia import dna_to_oiia

dna_to_oiia({"example": "ATCGGATTA"}, "output")  # Creates output.wav
```

### Convert a FASTA File
```python
from dna2oiia import dna_to_oiia, process_fasta

sequences = process_fasta("example.fasta")
dna_to_oiia(sequences, "output")
```

### Stream Audio to a Buffer
```python
import io
from dna2oiia import dna_to_oiia

buf = io.BytesIO()
dna_to_oiia({"example": "ATCGGATTA"}, output_buffer=buf)
# buf now contains WAV data, seeked to start
```

### Speed and Repeat
```python
from dna2oiia import dna_to_oiia

dna_to_oiia({"fast": "ATCGATCG"}, "fast_output", speed=2.0, repeat=3)
```

### Reverse Complement
```python
from dna2oiia import reverse_complement

rc = reverse_complement("ATCG")  # "CGAT"
```

### Validate a Sequence
```python
from dna2oiia import validate_dna_sequence, InvalidDNASequenceError

validated = validate_dna_sequence("atcgu")  # Returns "ATCGU"

try:
    validate_dna_sequence("HELLO")
except InvalidDNASequenceError as e:
    print(e)  # Invalid characters: E, H, L, O
```

## 🌐 Streamlit Web App

Run an interactive web app to convert DNA/RNA sequences to audio:

```bash
pip install dna2oiia[streamlit]
streamlit run st_dna2oiia.py
```

Features:
- Paste a sequence or upload a FASTA file
- Adjust playback speed with a slider
- Play and download generated audio

## 🎉 Acknowledgments

This project was inspired by a conversation with my IOB friends Nathan and Ibukun during a hackathon trip. Their creative thinking sparked the idea of transforming DNA sequences into sound. Huge thanks for the inspiration!

## 🎶 Audio Source Attribution

The **"oiia"** sound used in this project was sourced from the following YouTube video:

[🔗 Original Video on YouTube](https://www.youtube.com/watch?v=1oKZFGLn02g)

The meme itself originates from viral internet content. This project does not claim ownership of the original meme audio but uses it under **fair use** for creative and educational purposes.

## 🤖 AI Assistance

This project was developed with assistance from AI tools to improve code structure, refine documentation, and troubleshoot issues.

## 📜 License
This project is licensed under the MIT License.

## 🤝 Contributing
Contributions are welcome! Feel free to open issues and pull requests.

