Skip to main content
Make sure you’ve completed the Installation steps before proceeding.

​
Getting started

Follow these steps to start using Open Tarteel:
1

Start the development server

Run the development server with one of these commands:
npm run dev
For faster development with Turbopack, use npm run dev:turbo
The application will start at http://localhost:3000
2

Access the application

Open your browser and navigate to http://localhost:3000. You’ll see the main interface with:
  • Logo/Hero section at the top
  • Reciter selector in the center
  • Language toggle in the navigation
src/app/page.tsx
export default function Home() {
  const selectedReciter = useAtomValue(selectedReciterAtom);
  
  return (
    <div className="flex w-full flex-col items-center justify-center gap-y-4">
      <Logo />
      <ReciterSelector />
    </div>
  );
}
3

Select a reciter

  1. Click on the Reciter Selector button
  2. Browse through the list of available reciters
  3. Use the search bar to find a specific reciter by name
  4. Filter by Riwaya (recitation transmission method) if desired
  5. Sort by Alphabetical, Popular, or Views
  6. Click on a reciter card to select them
You can mark reciters as favorites by clicking the star icon on their card
4

Choose a Moshaf

Each reciter may have multiple Moshaf (complete Quran recordings) with different Riwaya styles. Select the one you prefer to start playing.
5

Start playing

Once a reciter is selected, you’ll be redirected to /reciter/{id}?moshafId={moshafId} where the audio player becomes active. You can now:
  • Play/pause the recitation
  • Navigate between Surahs
  • Adjust volume and playback speed
  • Enable shuffle or repeat modes
  • View the audio visualizer

​
Player controls

The audio player provides comprehensive controls:

​
Basic controls

Play/Pause

Start or pause the current Surah playback

Next/Previous

Navigate between Surahs in the playlist

Volume

Adjust the audio volume (0-100%)

Progress

View playback progress and seek to any position

​
Playback modes

Plays through the playlist in order. When the current Surah ends, it automatically plays the next one.
src/jotai/atom.ts
export type PlaybackMode = 'off' | 'shuffle' | 'repeat-one';
export const playbackModeAtom = createAtomWithStorage<PlaybackMode>(
  'playback-mode',
  'off'
);

​
Advanced features

Adjust the playback speed from 0.5x to 2x:
  • 1x - Normal speed (default)
  • 1.5x - Faster for review
  • 2x - Maximum speed
  • 0.5x - Slower for learning
src/jotai/atom.ts
export const playbackSpeedAtom = createAtomWithStorage<number>(
  'playback-speed-value',
  1
);
View and manage the complete playlist of 114 Surahs:
  • Click the playlist icon to view all Surahs
  • Jump to any Surah directly
  • See Surah names in Arabic or English
Enable or disable the real-time audio visualizer:
  • Toggle from the player controls
  • Shows frequency spectrum during playback
  • Can be disabled to improve performance
src/jotai/atom.ts
export const showVisualizerAtom = createAtomWithStorage<boolean>(
  'show-visualizer',
  true
);
Set a timer to automatically pause playback:
  • 5, 10, 15, 30, or 60 minutes
  • Until End - Stops after current Surah
  • Perfect for bedtime listening
Access from the “More options” menu in the player controls.

​
Favorites system

Save your preferred reciters for quick access:
1

Add to favorites

Click the star icon on any reciter card to add them to your favorites
2

View favorites

Toggle the “Show Favorites Only” filter to see only your favorited reciters
3

Sync across devices

Favorites are stored locally and synced via GunDB, allowing you to access them across different devices (when online)
src/jotai/atom.ts
export const favoriteRecitersAtom = createAtomWithStorage<string[]>(
  'favorite-reciter',
  []
);

​
Media session integration

Open Tarteel integrates with the Media Session API, allowing you to control playback from:
  • Lock screen controls (mobile)
  • System media controls (desktop)
  • Bluetooth/headphone controls
  • Notification area
src/hooks/use-media-session.ts
if ('mediaSession' in navigator && selectedReciter) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: surah?.name || 'Unknown Surah',
    artist: selectedReciter.name,
    album: selectedReciter.moshaf.name,
  });
}

​
Fullscreen mode

For an immersive experience, enable fullscreen mode:
  1. Click the fullscreen icon in the player controls
  2. Press F11 (on desktop browsers)
  3. Exit with Esc key or the exit fullscreen button
src/jotai/atom.ts
export const fullscreenAtom = createAtomWithStorage<boolean>(
  'fullscreen',
  false
);

​
Install as PWA

Open Tarteel can be installed as a Progressive Web App:
  1. Open Open Tarteel in your browser
  2. Look for the install icon in the address bar
  3. Click Install when prompted
  4. The app will be added to your applications
Or use the browser menu: More Tools → Install Open Tarteel
Installing as a PWA provides offline access to previously played Surahs and an app-like experience

​
Keyboard shortcuts

Speed up your workflow with keyboard shortcuts:
ShortcutAction
Arrow DownNavigate to next reciter (in selector)
Arrow UpNavigate to previous reciter (in selector)
EscapeReturn to search input (in selector)
F11Toggle fullscreen (browser)
More keyboard shortcuts may be added in future updates

​
Language settings

Switch between Arabic and English:
  1. Click the language toggle in the navigation
  2. The interface will switch immediately
  3. Arabic enables RTL (right-to-left) layout
  4. English uses LTR (left-to-right) layout
src/jotai/atom.ts
export const localeAtom = createAtomWithStorage<'ar' | 'en'>('locale', 'ar');

​
State management

Open Tarteel uses Jotai atoms for state management. All user preferences are automatically saved:
  • Selected reciter
  • Favorite reciters
  • Playback mode
  • Volume level
  • Playback speed
  • Language preference
  • Visualizer state
  • Fullscreen state
import { useAtomValue, useSetAtom } from 'jotai';
import { selectedReciterAtom } from '@/jotai/atom';

// Read atom value
const selectedReciter = useAtomValue(selectedReciterAtom);

// Write to atom
const setSelectedReciter = useSetAtom(selectedReciterAtom);

​
Troubleshooting

  • Check your device volume
  • Verify the reciter’s server is accessible
  • Try refreshing the page
  • Check browser console for errors
  • Check your internet connection
  • The app fetches from MP3 Quran API - ensure it’s accessible
  • Try clearing browser cache
  • Check if you’re behind a firewall blocking external APIs
  • Ensure you’re using HTTPS or localhost
  • Check browser compatibility (Chrome, Edge, Safari recommended)
  • Clear browser data and try again
  • Verify service worker is registered (check DevTools → Application)
  • GunDB requires internet connection for sync
  • Check browser console for GunDB connection status
  • Favorites are stored locally first, then synced when online
  • Try clearing GunDB cache in localStorage

​
Tips for best experience

Use PWA mode

Install as a PWA for offline access and better performance

Enable visualizer

Turn on the audio visualizer for a more engaging experience

Create favorites list

Mark your favorite reciters for quick access

Try different modes

Experiment with shuffle and repeat modes for varied listening

​
Next steps

Features Overview

Explore all features in detail

User Guide

Learn how to use the app effectively

Technical Details

Understand the technical architecture

Contributing

Contribute to Open Tarteel

Build docs developers (and LLMs) love

Get started for freeTalk to us