shabados/mobile

Android and iOS app for searching, navigating, and presenting the Shabad OS database.

Presenter

Software for searching, navigating, and presenting the Shabad OS Database

About

Shabad OS Presenter can be used to display bani & gurbani in the home or at the gurdwara. A server model allows multiple devices to act as a display or a controller. The same model enables live captions to be in sync with the projector / presentation device.

For more, please see:

• Our Website
• Install Shabad OS Presenter
• How to Add Bani Captions to a Live Stream

Features

• Multiple displays and controllers synced together
• Live broadcast captioning / subtitling
• Curated design
  • Text legibility/readability
  • Organized UI/UX functionality
• Keyboard shortcuts
  • Search, History, Bookmarks
  • Jump to line N of shabad
  • Autoselect line based on context/position

Screenshots

Contribute

If you want to help, please get started with the CONTRIBUTING.md doc.

Community

The easiest way to communicate is via GitHub issues. Please search for similar issues regarding your concerns before opening a new issue.

Get organization updates for Shabad OS by following us on Instagram and Twitter. We also invite you to join us on our public chat server hosted on Slack.

Our intention is to signal a safe open-source community. Please help us foster an atmosphere of kindness, cooperation, and understanding. By participating, you agree to abide by the Contributor Covenant.

If you have a concern that doesn't warrant opening a GitHub issue, please reach out to us:

• Harjot Singh, Maintainer: @harjot1singh
• Bhajneet S.K.: @bhajneet

"Thank you!" to all the volunteers who've contributed to Presenter.

mobile's Issues

add search options pop-up button

For refining or re-arranging search results

• Button near search bar/input box (see mockup below)
• The pop-up modal would will have options (see mockup below)

Mockups

add search filters scrolling strip

Example mockup below. The search filters scrolling tab is just below the input box for search. By default no filters are on.

The search is meant to be interpretive, e.g. type latin man, return results for:

• transliteration: bhe puneet pavitr man janam janam ke dukh hare |1| rahaau |
• translation: Because, he created angels out of ordinary human beings,

Or, e.g. type gurmukhi ਨਨਕ, return results for

• first letters: ਨਿਹਕੰਟਕੁ ਨਿਹਕੇਵਲੁ ਕਹੀਐ ॥
• main letters: ਨਾਨਕ ਹੁਕਮੈ ਜੇ ਬੁਝੈ ਤ ਹਉਮੈ ਕਹੈ ਨ ਕੋਇ ॥੨॥

And we also interpret results to help users. For example if the user types nanak with extra character on last letter, then we can search the main letters, in case the full word doesn't return results, after the full word results (see in mockup top results, first letters, headers we would have main letters after full words in this example).

So users may wish to turn on/off these extra search modes or search targets. To help refine the results, these filters are available. Users may refine by:

• Search target (i.e. Bani, Translation, Pronunciation, that's it)
• Search mode (i.e. First Letters and Main letters, that's it)
• Composition (e.g. Sri Guru Granth Sahib Ji, Dasam Granth, ...)
• Author (Guru Nanak Dev Ji, Bh Nand Laal ji, ...)

The last two are perhaps better done as filter/sort dropdowns in a pop-up/modal window a la #42

Related to shabados/presenter#395

Add "group by pauri"/"paragraph reading mode" option

See shabados/presenter#442

Add dynamically updating bookmarks

From various gurdwaras. Add date to side.

New issue for "Add ability for gurdwaras to update their hukamnama"

add search input switcher (keyboard / ascii to gurmukhi vs unicode)

This would be in addition to the normal/default keyboards of Android / iOS (which already come bundled with latin and gurmukhi keyboards). This is for users that don't know how to switch to unicode keyboards in android/iOS.

This switch would convert ascii characters to gurmukhi unicode in the search bar/input box.

Different ways to do it:

• The button changes the keyboard of the OS (not sure if this is possible? but even if it were it doesn't help people with external keyboards I don't think)
• The button pops up a custom keyboard (benefit here is that external keyboards are still inputting ascii characters as the custom keyboard inputs ascii latin which is auto converted by search input, and we also get to lay out the characters as we think it's easiest for users). Direct translation of shabados/presenter#394

The toggle would also change the search input. If the input is already in unicode gurmukhi, do nothing. If it were in latin characters (e.g. jkm), then toggling on would convert these letters (e.g. ਜਕਮ).

This allows the search to be much more fluid/easy. If the user typed it in wrong, they could always toggle the button to convert the search without re-typing it. If the user wants to switch from gurmukhi (first letter, full word, main letters, pronunciation, etc.) to latin (translation, translit, etc.) it's an easy toggle.

Not sure yet whether this button will be in/on left side of search bar/input box or if it will be part of the filter/sort button menu (if we have a filter/sort button menu) related to #42 and #43

google developer play store signup + setup

Add method to submit "source verifications" / ask for corrections

Users should be able to link a github account. Need to attach camera picture (open camera to take one) or existing image.

The line that the user is trying to "correct" / "verify" would follow the same template as db repo corrections do today.

Allow bookmarks and folders to open in reader mode

Allow user to define certain bookmarks and folders to open in reader mode by default.

Add long-press menu

Long press a line should show some options or pop-up with this research mode. Long pressing should allow setting a line as main, it should allow creating a bookmark with that line as the title of the bookmark, it should also allow for more advanced features like making notes, listening to katha for the line, reading exegesis/discourse, and seeing translations, pronunciations/shudh ucharan, and dictionary list of all the words in the line.

These different options can be tabs (where indicated by red words). So proposal to have these tabs eventually (can break into separate issues to track):

• Translations
• Dictionary
• Pronunciation (if we ever in the future include a text-to-speech option perhaps this could go in here as basic pronunciation with reading notes for more clear / nuanced shudh ucharan)
• Notes
• Exegesis (reading, pdfs, or links to different youtube/audio clips of katha / paath reading)
• Other (don't know whether to categorize above, keep in separate tab, or add as two step options where you highlight the line and do these actions or open research mode, can be discussed): bookmark, set as main line, print, share line, submit correction, read source pdf, etc.

These tabs can perhaps be changed by swiping left and right. They may be too long, so scrolling up and down should be possible.

The bottom should include ways to change the line you're highlighting. In mockup it's just arrows, but can be labeled buttons with a short preview of the line it's changing to.

The highlighted line should fit in the background shown above the research mode drawer, the background above should perhaps not continue scrolling as the tab normally does since that could be the action used to close the drawer (pulling down) this can be discussed. If we do enable scrolling of the background tab (I wouldn't recommend this personally, but we can test), then it should select new lines based on what is closest to the middle.

Marked as high impact as the entirety of this issue will surely affect most users. However, as we break down this issue, we can change the impact levels of each individual section.

Implement bookmarks

Bookmarks should act on the current tab, bookmarks should include:

• Folders (events, gurpurabs, themes, etc.)
• Dynamic bookmarks
• Regular shabad/dictionary bookmarks (user definable)
• Compilations / banis (e.g. nitnem, asa ki vaar)

Mockup example:

Link Media to Tuks/Shabads

This could serve two purposes, either for personal use or to populate a public DB. For personal use, a user could record voice memos and/or link to private files on their phone. For a public DB, they could link URLs to shabads/tuks. Shabad OS would not be hosting the media.

From a UI perspective, public links could be shared in Shabad Info at top of tab, or in "Research Mode." For private files, might be featured in a bookmarks folder, or a separate view of its own. Need to discuss further.

Capture Test Result and Code Coverage

Pin lines in shabad view

User should be able to pin lines from #41 menu. Pinned lines should always be in view. When scrolling through the shabad, if the line is about to go off the screen, pin to that end of the screen. If it's in the middle of the page, it should scroll with the rest of the shabad.

Should be able to pin multiple lines if they are sequential.

Add ability to run present mode with usb-c / lightning cable

Related #30

Add random shabad to explore page

When to update? once a day, never at all and require pressing the shuffle button, etc.

Continuous Internal Next Releases

User Story

As a registered test user, I'd like to install and update the app easily, so that I can test and provide app feedback.

Acceptance Criteria

AC1

Given an unregistered test user
When they are added to the internal test distribution group on app center
Then they can download next releases for iOS or Android

AC2

Given a registered user with the app downloaded
When an native update is pushed out
Then the user receives an email to download the latest app
And the user receives a clickable push notification (from either the app or testflight) about the update

AC3

Given a developer has merged a change into the trunk
When the CI pipeline has passed
Then the iOS and Android builds should be released to the test distribution group on App Center

Approaches

❌ Approach 1 (Fastlane + App Center + Codepush) [Ad-hoc, limited]

• Build with Fastlane in CI
• Create a release in App Center using Fastlane in CI
• [Create a release in App Center CodePush using CI (Fastlane?)]

Pros: Instant, no-review releases (until App Store actual release); No TestFlight App required; No App Expiry;
Cons: Limited to 100 devices on Apple account with 1 year period for changes;

✅ Approach 2 (Fastlane + [Testflight & Google Play] + Codepush) <-- we're going with this!

• Build with Fastlane in CI
• Create a release in Testflight using Fastlane in CI
• Distribute release in Testfight to internal testers & general testers (primarily for app review feedback)
• Create a release in Google Play using Fastlane in CI
• Distribute release to Google Play testers
• [Push to MS App Center Codepush in CI]

Pros: Unlimited users on group, email-address based user-management; Earlier reviews
Cons: Manage distribution groups in both Google Play and Testflight; App Build expires after 90 days; Additional tool in stack (MS)

❌ Approach 3 (Fastlane + [Testflight & Google Play] + Expo-update)

• Build with Fastlane in CI
• Create a release in Testflight using Fastlane in CI
• Create a release in Google Play using Fastlane in CI
• [Push to somewhere with expo-update??]

*Pros: No need to add/manage MS App Center;
Cons: More complexity??

Sub-tasks

• Add users to App Store Connect
• Create Google Play Account
• Add users to Google Play
• #154
• #155

Questions

• Does App Center make user group distribution unified? Or do we still have to add users to the respective distribution platforms?
• Do we care about waiting for an app center review for internal release? Nope, we have codepush and shouldn't be too bad -> no need for ad-hoc. Sounds like preferably we'd want a way of adding user email addresses in one place that'd in either internal distribution groups (to help with registering device UUIDs for no-review releases) and mainly adding email addresses for all testers (review-releases).
• [Does expo-updates give us anything over codepush? Is it the same implementation effort?]
• ** Certificate signing?? Can we avoid dealing with this ourselves entirely?** Might need an additional task here

Notes??

• TestFlight has the superior UX over App Center vs CodePush

Agreements

• We only would distribute next releases to non-SOS team for the sake of preview, once app is out, they'd not need the next releases -> let's optimise for the SOS team's perspective/ease
• Next releases are primarily for UAT'ing
• CodePush will not be covered in this ticket - it is covered in #13

Blocked By

• #146
• #160

Select Multiple Lines from Long Press & Drag

Similar function to selecting "Select multiple lines..." from #41 menu.

Android / iOS UI Test

We'd like to make sure that there are no issues using React Native to implement the same features across both platforms. The specific functionality we'd like to test are:

• Standard Shabad View (test scrolling) (#94)
• Draggable Drawer (#93)
• Search button and search modal functionality as per Figma mockup (#95)

Add title to tabs

Should be what was searched or set to the main line when it is changed by the user.

Option to add "Info" section beneath this, which would include clickable link to "Ang"

Add CodePush support

Enable App Center codepush so that we can release updates to the app without having to go through a formal appstore release process (which can take days).

AC2

Given a registered user with the app downloaded
When an non-native update is pushed out
And the registered user opens the app
Then the user instantly has the latest update (via codepush)

Blocker: we need to check whether we'd like to go with expo-updates or app center codepush!

Experiment A/B Framework

Add personalized/local daily hukamnama

Requirements:

• Updates once a day or manually by user
• Randomly selected from Sri Guru Granth Sahib's selection of hukamnama shabads
• Not requiring a perma-tab to keep saved

Keep screen on option

An option to keep the screen awake when the app is running

Setup E2E Testing

User Persona, Goal, and Motivation

I am a developer, I want to automatically test feature integration, so that I can make sure they all continue to work properly with each other.

No sub-tasks, they're technically in #128 already (which in the future will be tasks/sub-tasks)

Approach

• Use Detox #128

Add ability to chrome cast

This should create a presenter view on the chromecast

Selecting lines in Shabad OS should update the chromecast.

Requires some form of "server" for multiple controllers to affect the presentation started by first chromecast-er.

Can go in this menu for now (bottom right of mock-up):

Add UID search

If user searches 3 or 4 letter codes show the relevant shabad/line in search. If user searches a line this way, instead of opening the shabad, perhaps it should open a GitHub issue convo (if exists) for line corrections in db repo. Could then open shabad / "page" (ang, panna, kabit, etc.) for context if user wishes.

Could then tie reversely from #41 for long pressing lines and checking github/corrections for it.

Add paath bookmark for different compositions

• Should remember last line read/position
• Should be able to update page (could perhaps use the same function as "go to" in other bookmarks like asa ki vaar for jumping chukke?), this is useful for when multiple people are doing a shared paath and need to update their bookmarks to the correct page
• Should be easily start-able. How does a user begin a paath bookmark or convert a bookmark into one that follows the above two requirements?

Linting

TsLint + Prettier

Add scrolling/continuous-scrolling functionality

Ideas:

• Tap lines to set speed (basically program notices line length and speed of "activating" line, and calculates speed based on that)
• Use line length to help refine speed, don't scroll too fast if lines are filling up screen, but speed up scrolling if lines don't wrap and have paragraph breaks, etc.
• Make sure to not scroll if starting from top of content (assume first most line is active and has to be read through)
• Indicate speed somehow (perhaps indicate which line is being read with a highlighted background and fill it up slowly as it's being "read" by program, this would be annoying if speed is off and keeps highlighting the wrong line though)
• need to know the height of words based on font size and the viewer port height (as font size increases, page scrolling speeds up too), track font size in implementation

Add "hints" or mini-tutorials / tips component

User Persona, Goal, and Motivation

I am a developer, I want users to know other ways to interact with the app, so that I can feel rest assured that users understand how to use the app.

I am a developer, I want to shepherd users understanding of new features dropped, so that they may learn it.

I am a new user, I want to learn how to search more effectively, so that I can find my results faster.

I am a new user, I want to learn how to bookmark, so that I can organize shabads better.

Acceptance Criteria

AC1

• GIVEN
• WHEN
• THEN show a floating card with arrow pointing to element

And

• GIVEN A floating card is shown
• AND GIVEN centerpoint of element being pointed to is on right third (1/3) of screen
• WHEN
• THEN floating card should be closer to the right with a gap on the left (see mock)

AC2

• Given
• When
• Then show an inline card

And

• Given inline card is shown
• When user scrolls
• Hint/mini-tutorial/tip inline card should scroll with content

Approach

• [ ]

Mockup

Old

Say for example the user taps the same line 3 times in 3 seconds, perhaps they're confused why more options don't show up. So we can add a hint that pops up above the line that says "Long press a line to make a note or do more research".

Once there is a way to add these kinds of hints, then we should go through the UI and think of good ways to help users improve their experience. Perhaps a hint on first search or long scrolling results to remind users of the filter button to narrow down what they're looking for.

Etc.

Release Notes

Add next gesture at bottom and prev at top

Scrolling to the bottom should come to a full stop. Scrolling up from there can pull the next shabad, page, bookmark (depending on what the user has opened in that tab).

Registration/Login/Authentication

Epic supporting:

Registration
Login

This will then allow us to support moving from desktop, web, mobile

Add ability to apple air tv

Related #30

Select Multiple Lines...

After selecting multiple lines (either by long-press and drag as in #52 or from pane 1 of #41 menu), a bar at the bottom should give similar options to pane 1 of #41 such as copy, share, print, pin, and cancel.

Social Media or other notifications of a new release

On Blank Search, offer "suggested" searches

Such as "Search by Ang"

Related #37

Can phone volume buttons be hotkeys for the mobile browser when remote controlling shabad os on the same network?

Set line in middle of scrollable section of navigator as pseudo "current line"

Context: If a user has a keyboard and uses the up and down arrow keys, we "center" the current line in the viewport. On mobile we need a "current" line to make good use of: bookmark in quick drawer, history (main line title, current line subtitle), automatically updating progress in paath (sehaj paath, shared akhand paath), etc.

Solution is to set the current line as whatever's scrolled closest to the center. If "grouping by pauri" use first line of pauri for compatibility with users not grouping by pauri/not using reader mode.

Can show pseudo selector around the line. Explicit clicking of line for actual select (or sending to screens). Explicit click trumps pseudo select? Need to discuss that in context of paath vs control mode.

Can help explain animation of pseudo select later

Create React Native base project with Typescript support

Create a basic skeleton project

Add method to connect to other Shabad OS for reading/controlling purposes

Related Add remote control without wifi / "Shabad OS Connect" shabados/presenter#416

This would allow mobile users to quickly connect to local shabad os running in their area. It must also require the ability for mobile users to follow along at home for live streams without captioning (or those wanting personalized captioning).

Need to differentiate read/control mode being activated. Proposal to add a green or red dot in corner (like notification badges on app icons) for "more" icon. Could also add a bar to the top that says "connected" and color the background of that bar and add a few icons to that bar for "cancelling/reload"etc? Need a "grey" color to define "reconnecting/lost connection state".

Need to identify what happens when someone tries to reconnect after the program is done / user closed app for hours.

Continuous Integration

Offline search

Needs to be split into two stories: poor data and no data to cut down effort.

User Persona, Goal, and Motivation

I am a user at a sangat-gathering with poor data connectivity, I want to search, so that I can read the Shabad that is being sung.

Acceptance Criteria

AC1

• GIVEN the user searches for a shabad
• WHEN the user has no connectivity (as reported by the OS)
• THEN no connectivity + limited results messaging appears to the user
• AND fallback results are returned from database search

AC2

• GIVEN the user searches for a shabad
• WHEN the search takes longer than 200ms
• THEN a search spinner appears

AC3

• GIVEN the user searches for a shabad
• WHEN the search takes longer than 2s
• THEN poor connectivity + limited results messaging appears to the user
• AND fallback results are returned from database search

Notes

• We may want to switch the user over to limited searching for the rest of the session/until good connectivity - let's look at analytics to determine necessity

Approach

• #164
• #165
• #166
• #168
• #167
• #169

Mockup

Ideas

Google's approach

• Spinner only added after N ms rather than instantly
• Poor connection + Limited search results messaging displayed to user

Old

Users should have a way to search things offline if they're not connected to the API

Though this affects a few users at odd times, it is crucial for those moments. So low impact, but high priority for stable experience.

Finish mocking up android

The iOS version is complete enough. Need to finish Android and then make sure workflows/ui/ux is relatively consistent and doable across both.

Continuous Delivery

All things to enable mobile apps being able to be released continuously.

Add reader mode

User Persona, Goal, and Motivation

I am a traditional reader, I want to view gurbani like I would in a gutka, so that I can do paath comfortably (less scrolling and visually more natural).

Acceptance Criteria

AC1

• Given a user is on the settings screen
• When they toggle the reader mode element
• Then the reader mode is toggled on/off

AC2

• GIVEN shabad is shown
• WHEN reader mode is toggled
• THEN show only shabad script in paragraphs of pauris (no translations and transliterations)
• And the font is larger

AC3

• GIVEN reader mode is toggled
• WHEN displaying manglacharan / header lines
• THEN show them as individual lines in a larger font, center-aligned (see mock)

AC3 may be revisited as a future ticket, as we may not have the data available. @bhajneet to move into a new ticket.

Approach

• #235
• #236

Mockup

Old

Have an option to quickly switch the view to "reader mode" which may group pauris together in paragraphs, may also hide all translations, may switch to larrivaar, etc. based on whatever the user has dictated in "reader mode settings".

Could then add new issues for setting bookmarks to open in specific reader mode on a case by case or overall "type of bookmark" method.

ios developer store signup + setup

Release

Add localisation option to Setting pane

User Persona, Goal, and Motivation

I am a non-English user, I want to see the UI in a readable language, so that I can naturally interact with Shabad OS.

Acceptance Criteria

AC1

• GIVEN user is on the Settings pane
• WHEN the user taps "App Language" button
• THEN the "App Language" drawer is viewable with language options
  • pa-in (punjabi)
  • en-gb (english uk)
  • en-us (english us)

AC2

• GIVEN the user is viewing the "App Language" drawer
• WHEN user taps a language option
• THEN that language gets a filled green circle
  • AND the drawer automatically closes
  • AND setting of "App Language" in Settings pane is updated with selected language

AC3

• GIVEN "App Language" drawer is on screen
• WHEN user taps any of the following:
  • Currently selected language
  • Cancel button
  • Outside the drawer
  • Dragging down the drawer
• THEN drawer disappears without updating anything

AC4

• GIVEN an app language is chosen
• WHEN some aspect of the UI is being shown
• THEN the localised components should be displayed in the chosen language

Approach

• #210
• #211
• #212

Mockup

Related

• Resource: https://github.com/stefalda/ReactNativeLocalization
• Base work done in #116

Blocked By

• #172
• #215

Sync/Backup user settings, bookmarks, paath progress, etc.

Users should be logging in or backing up to google drive / iCloud for multiple device syncing. Very helpful for when users switch phones or for users that use Shabad OS desktop in addition to mobile. Creates a feeling of "security" in case one's physical device is damaged/lost.