Skip to content

README.md

Latest commit

 

History

History
267 lines (180 loc) · 9.4 KB

README.md

File metadata and controls

267 lines (180 loc) · 9.4 KB
Raw
Sundar Gutka Logo

Sundar Gutka

Platform Slack React Native Yarn

Sundar Gutka is a feature-rich mobile application that provides access to Gurbani with extensive customization options for reading preferences, audio playback, translations, and more. The app supports both iOS and Android platforms and offers a seamless experience for daily Paath.

✨ Features

Reading Features

  • Multiple Font Options: Choose from various Gurbani fonts including GurbaniAkharTrue, GurbaniAkharThickTrue, BalooPaaji, AnmolLipi, and more
  • Adjustable Font Size: Five size options from Extra Small to Extra Large
  • Larivaar Mode: Read Gurbani in continuous text format with optional assist mode
  • Paragraph Mode: Toggle between traditional and paragraph formatting
  • Vishraam Options: Color-coded or gradient punctuation marks for better reading flow
  • Auto Scroll: Automatic scrolling synchronized with audio playback
  • Bookmarks: Save and quickly navigate to your favorite Shabads
  • Position Saving: Automatically saves your reading position for each Bani

Translation & Transliteration

  • Multiple Languages: Support for English, Hindi, Punjabi, Spanish, French, Italian, and more
  • Transliteration: Romanized text options (English, Hindi, Shahmukhi, IPA)
  • Translations: English, Punjabi, and Spanish translations available
  • Multi-language UI: Interface available in multiple languages

Audio Features

  • Audio Player: Built-in audio playback with React Native Track Player
  • Audio Sync: Synchronized scrolling with audio playback
  • Background Playback: Continue listening when app is in background
  • Auto Play: Automatic audio playback option
  • Default Audio Selection: Choose preferred audio source

Customization Options

  • Theme Support: Light and Dark themes
  • Bani Order: Customize the order of Banis in your Gutka
  • Bani Length: Select from different lengths (SGPC, Taksal, Medium, Long, Extra Long) for major Banis
  • Keep Screen Awake: Prevent screen from sleeping during reading
  • Status Bar Control: Show or hide status bar

Additional Features

  • Folders: Organize Banis into folders
  • Reminders: Set up notification reminders for daily Paath
  • Database Updates: In-app database update functionality
  • Statistics: Optional usage statistics collection
  • Donation Support: Support the Khalis Foundation

🚀 Getting Started

Prerequisites

Installation

  1. Clone the repository:

    git clone https://github.com/KhalisFoundation/sundar-gutka-react.git
cd sundar-gutka-react

  2. Install dependencies:

    yarn install

📱 Platform Setup

Android Development

  1. Environment Setup: Follow the React Native Android setup guide

  2. Run the application:

    yarn android

  3. Start Metro Bundler (if not started automatically):

    yarn start

iOS Development

  1. Environment Setup: Follow the React Native iOS setup guide

  2. Install CocoaPods dependencies:

    cd ios
pod install
cd ..

  3. Run the application:

    yarn ios

  4. Start Metro Bundler (if not started automatically):

    yarn start

🏗️ Project Structure

For detailed project structure information, see PROJECT_STRUCTURE.md.

🛠️ Key Technologies

📝 Available Scripts

  • start: Start Metro bundler with ESLint
  • android: Run Android app with ESLint
  • ios: Run iOS app with ESLint
  • lint: Run ESLint
  • test: Run tests

⚙️ Configuration

Firebase Setup

The app uses Firebase for:

  • Analytics
  • Crashlytics
  • Push Notifications (Messaging)
  • Performance Monitoring

Ensure google-services.json (Android) and GoogleService-Info.plist (iOS) are properly configured.

Database

The app uses SQLite for local storage. Database files are located in:

  • iOS: ios/www/gutka_v01.db
  • Android: Bundled with the app

🎨 Customization

Themes

The app supports light and dark themes. Theme configuration is located in src/theme/.

Fonts

Custom fonts are located in assets/fonts/. Supported fonts include:

  • GurbaniAkharTrue
  • GurbaniAkharThickTrue
  • GurbaniAkharHeavyTrue
  • BalooPaaji2-Regular
  • BalooPaaji2-SemiBold
  • AnmolLipiSG

Localization

Localization strings are managed in src/common/localization.js. The app supports multiple languages for the UI.

🧪 Testing

Run tests with:

yarn test

🎵 Audio Assets (M4A)

All audio files used in this app are in M4A format (AAC 128kbps inside an MP4 container). M4A is required over MP3 because ExoPlayer on Android can seek accurately within M4A files using the container's built-in index — this is what makes sync scroll work correctly on Android. MP3 seeking is estimate-based and causes progressive drift.

Creating M4A Files

To convert a source audio file to the correct M4A format:

ffmpeg -y -i input.mp3 -codec:a aac -b:a 128k -map_metadata 0 -movflags +faststart output.m4a
  • -codec:a aac — encodes audio as AAC inside an MP4 container
  • -b:a 128k — 128kbps constant bitrate
  • -movflags +faststart — moves the MP4 index (moov atom) to the front of the file so ExoPlayer can begin streaming instantly with a single HTTP request. This flag is mandatory — without it, streaming triggers multiple network round-trips before playback can start
  • -map_metadata 0 — preserves original metadata tags

Important Notes

  • Never use MP3 — ExoPlayer's inaccurate seeking on MP3 breaks sync scroll on Android
  • Always include -movflags +faststart — skipping it will cause buffering on stream seek
  • File naming: Use PascalCase (e.g. JapjiSahib.m4a, not japji-sahib.m4a)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For detailed contribution guidelines, please see CONTRIBUTING.md.

Before raising a pull request, please go through CONTRIBUTING.md. We use dev branch as the development branch, while master is the production branch. You should branch out from dev branch and raise a PR against dev branch.

  1. Fork the repository
  2. Create your feature branch from dev (git checkout -b feature/AmazingFeature dev)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request against the dev branch

📄 License

This project is maintained by the Khalis Foundation.

🙏 Acknowledgments

  • BaniDB: Sundar Gutka utilizes the open source Gurbani database and API used in many Gurbani applications, such as SikhiToTheMax
  • Khalis Foundation: For maintaining and supporting this project

📞 Support

For information, suggestions, or help, visit:

⚠️ Important Notes

  • Please respectfully cover your head and remove your shoes when using this app
  • The app respects different sampardhas (traditions) and provides options for various Bani lengths while maintaining SGPC/Akaal Takht standards
  • Bhul Chuk Maaf! (Please forgive any mistakes)