README.md

metadata

title: Text Transformer
emoji: ⚡
sdk: docker
app_port: 7860

T3XT TR4N5F0RM3R 🎮

Your one-stop tool for text conversions ⚡

Demo • Features • Installation • Documentation • Contributing

---

🌟 Overview

Text Transformer is a modern, cyberpunk-themed web application for converting text into various formats. Built with React and featuring a sleek, animated interface, it supports multiple conversion types with bidirectional transformation capabilities.

✨ Features

🔄 Converters

• Morse Code - Convert text to/from Morse code with proper spacing
• Leet Speak - Transform text to/from 1337 5P34K
• Binary - Encode/decode text to binary representation
• Base64 - Standard Base64 encoding/decoding with Unicode support
• Hexadecimal - Convert text to/from hexadecimal notation
• Emoji - Text to emoji conversion (experimental)
• TinyLlama - AI-powered text generation using TinyLlama model
• MusicGen - AI music generation from text prompts and audio uploads

🎯 Core Features

• ✅ Bidirectional Conversion - Swap between input/output formats instantly
• ✅ Compounded Messages - Chain multiple conversions together
• ✅ Error Handling - Graceful error messages for invalid inputs
• ✅ Copy to Clipboard - One-click copying of results
• ✅ Responsive Design - Works on desktop, tablet, and mobile
• ✅ Accessibility - ARIA labels and keyboard navigation
• ✅ Cyberpunk UI - Animated, modern interface with neon aesthetics

🚀 Installation

Prerequisites

• Node.js 16+
• npm or yarn

Quick Start

# Clone the repository
git clone https://github.com/kwizzlesurp10-ctrl/converter.git
cd converter

# Install dependencies
npm install

# Start development server
npm run dev

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

Build for Production

# Build the project
npm run build

# Preview production build
npm run preview

Run with Docker (HF Space image)

Run the pre-built image from Hugging Face (TinyLlama/HF Inference needs a token):

docker run -it -p 7860:7860 --platform=linux/amd64 \
  -e VITE_HF_TOKEN="YOUR_VALUE_HERE" \
  registry.hf.space/onyxmunk-text-transformer:latest

Replace YOUR_VALUE_HERE with a Hugging Face token (or use --env-file .env if you have VITE_HF_TOKEN in .env). Then open http://localhost:7860.

On Windows you can run .\run-docker.ps1; it will use VITE_HF_TOKEN from your environment or from a .env file in the project root.

Deploy to Firebase

# Install Firebase CLI
npm install -g firebase-tools

# Login to Firebase
firebase login

# Deploy
firebase deploy

📸 Demo

Main Interface

Compounded Message Feature

Error Handling

MusicGen Audio Generator

🎨 Tech Stack

• Frontend Framework: React 18.3.1
• Build Tool: Vite 7.2.4
• Styling: Tailwind CSS 3.4.18
• Testing: Vitest + Playwright
• Hosting: Firebase Hosting
• Icons/Emojis: OpenMoji 16.0.0

🧪 Testing

# Run unit tests
npm run test

# Run tests in watch mode
npm run test:watch

# Build and verify
npm run build

🎵 MusicGen Setup (Optional)

The MusicGen converter requires a separate backend service to generate music. To use this feature:

Backend Requirements

• A MusicGen API service running on http://localhost:8000
• The service should expose a /api/musicgen/generate endpoint

Expected API Format

POST /api/musicgen/generate
{
  "prompt": "upbeat electronic dance music",
  "duration": 8,
  "melody": "data:audio/wav;base64,..." // optional
}

Response:
{
  "audio": "data:audio/wav;base64,...",
  "description": "Generated music description"
}

Setup Options

1. Use Meta's MusicGen: Follow the official MusicGen repository to set up the model
2. Use Replicate API: Integrate with Replicate's hosted MusicGen model
3. Use Hugging Face: Deploy using Hugging Face Inference API

Without the backend service, the MusicGen tab will display connection errors, but all other converters will work normally.

📁 Project Structure

converter/
├── src/
│   ├── components/          # Converter components
│   │   ├── MorseCodeConverter.jsx
│   │   ├── BinaryConverter.jsx
│   │   ├── LeetConverter.jsx
│   │   ├── Base64Converter.jsx
│   │   ├── HexConverter.jsx
│   │   ├── EmojiConverter.jsx
│   │   ├── TinyLlamaConverter.jsx
│   │   └── MusicGenConverter.jsx
│   ├── hooks/              # Custom React hooks
│   │   └── useConverter.js # Shared converter logic
│   ├── App.jsx             # Main application component
│   ├── main.jsx            # Entry point
│   └── index.css           # Global styles and animations
├── docs/                   # Comprehensive documentation
├── public/                 # Static assets
├── firebase.json           # Firebase configuration
├── vite.config.js          # Vite configuration
└── tailwind.config.js      # Tailwind configuration

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• Architecture Overview - System design and enhancement roadmap
• Quick Start Guide - Developer onboarding
• Role-Based Summary - Team structure and responsibilities
• Contributing Guide - How to contribute

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

🗺️ Roadmap

See our complete roadmap for planned features.

Phase 1 (In Progress)

• Core converters (Morse, Leet, Binary, Base64, Hex)
• Compounded message feature
• Error handling
• Accessibility improvements
• Additional converters (Upside Down, Zalgo, Markdown)

Phase 2 (Planned)

• User authentication
• Shareable links
• Conversion history
• Undo/redo functionality

Phase 3 (Future)

• Text-to-Speech
• Gamification features
• Custom character mappings
• Dark/Light theme toggle

🐛 Known Issues

• Browser view tab is experimental
• Emoji converter has limited character support

📄 License

This project is open source and available under the MIT License.

👨‍💻 Author

kwizzlesurp10-ctrl

• GitHub: @kwizzlesurp10-ctrl

🙏 Acknowledgments

• React team for the amazing framework
• Tailwind CSS for the utility-first CSS framework
• OpenMoji for emoji support
• All contributors and users

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ and ⚡ by the Text Transformer team

If you find this project useful, please consider giving it a ⭐ on GitHub!