Getting Started with Shrutik

Welcome to Shrutik! This guide will help you set up and start using the platform in just a few minutes.

Overview

Shrutik is a voice data collection platform that allows communities to contribute voice recordings and transcriptions in their native languages. You can either contribute data or set up your own instance of the platform.

Quick Setup Options

Option 1: Docker (Recommended)

The fastest way to get Shrutik running is with Docker:

# Clone the repository
git clone https://github.com/Onuronon-lab/Shrutik.git
cd shrutik

# Switch to the deployment-dev branch
git fetch origin
git switch deployment-dev

# Copy Docker environment configuration
cp .env.example .env

# Build images and start all services
docker compose up --build -d

Access the platform:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Note: For detailed Docker setup instructions, see our comprehensive Docker Local Setup Guide for configuration details, troubleshooting, and switching between local/Docker environments.

Option 2: Local Development

For development or customization:

# Clone and setup
git clone https://github.com/Onuronon-lab/Shrutik.git
cd shrutik

# Switch to the deployment-dev branch
git fetch origin
git switch deployment-dev

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

To start backend, frontend, and Celery worker, see the Local Setup Guide.

Verify Setup

Once you’ve successfully started the services using either Option 1 (Docker) or Option 2 (Local Development), confirm that everything is running correctly:

Check Backend Health

The backend provides a simple health endpoint to verify that the FastAPI server is up and running.

curl http://localhost:8000/health

Check Frontend

curl http://localhost:3000

First Steps

For Developers

1. Register an Account: Visit http://localhost:3000 and create an account
2. Start Recording: Begin with voice recordings or transcriptions
3. Track Progress: Monitor your contributions in the dashboard

For Administrators

1. Access Admin Panel: Login with your admin account
2. Configure Languages: Add supported languages and scripts
3. Manage Users: Review user registrations and assign roles
4. Monitor Quality: Review transcription quality and consensus

Contributing Voice Data

Recording Guidelines

• Environment: Record in a quiet environment
• Equipment: Use a good quality microphone
• Duration: Keep recordings between 2-10 seconds
• Content: Read the provided text clearly and naturally

Transcription Guidelines

• Accuracy: Transcribe exactly what you hear
• Formatting: Follow language-specific formatting rules
• Quality: Rate the audio quality honestly
• Consensus: Multiple transcriptions improve dataset quality

Troubleshooting

Common Issues

Services won’t start:

# All services
docker compose logs -f

# Specific service (example: backend)
docker compose logs -f backend

# Restart all services
docker compose restart

# Restart a single Service
docker compose restart backend

# Or check status
docker compose ps

Database connection errors:

# Stop services and remove volumes
docker compose down -v --remove-orphans
# (Optional) Clean unused Docker resources
docker system prune -f
# Rebuild and start all services
docker compose up -d --build

# Run migrations inside the backend container
docker compose exec backend python scripts/init-db.py
# If that fails, try the fallback
docker compose exec backend python scripts/simple-init.py

Permission errors:

# Fix file permissions
sudo chown -R $USER:$USER uploads/
chmod -R 755 uploads/

Getting Help

• Documentation: Check our comprehensive docs
• GitHub Issues: Report bugs and request features
• Discord: Join our community for real-time help
• Email: Contact us at onuronon.dev@gmail.com

Next Steps

• Local Development Guide - Set up development environment
• Docker Local Setup - Docker development environment
• API Reference - Integrate with external systems
• Contributing Guide - Contribute to the project
• Architecture Overview - Understand the system design

Welcome to the Community

You’re now ready to start using Shrutik! Whether you’re contributing voice data, developing features, or deploying your own instance, you’re part of a global movement to make voice technology more inclusive.

Join our community channels to connect with other contributors and stay updated on the latest developments.