Sangat Sync & Bani Controller

Sangat Sync and Bani controller are ways with which Sttm Desktop and Sttm Web can control each other. This is done through a special Sangat Sync API that can be used by any other app. Once the connection is established successfully desktop can control web (or other hosts) and vice versa

Sync API URL: https://api.sikhitothemax.org

Socket Source: ${SYNC_API_URL}/socket.io/socket.io.js

When talking about Sangat Sync, we will talk about two kinds of hosts

• Primary host / Desktop - The primary host is the one that generates namespace string and pin code so that all other secondary hosts can connect to it. In our case it's desktop, that's the primary host.
• Secondary host - which could be web, sunder-gutka, iGurbani, or any other app.

The data Event

There is only one event that we emit and listen to. This event is called data. Refer SikhiToTheMax API for more details on that. For this documentation, all we need to know is that all our socket emits and ons will be using the event name as 'data'.

Generate namespace String and Pin on Primary Host (Desktop)

First of all desktop requests API to generate a 6-word random alphabetic string. This string is called the namespace string. The API request looks like this

const result = await request(`${SYNC_API_URL}/sync/begin/${host}`);

After getting namespace string from API, a 4 digit numeric pin is generated on the desktop.

This step needs to be done only on the Desktop. If you are trying to merely connect a secondary host with Desktop, you don't need to perform this step.

After pin and namespace string is generated on desktop, the

Send Request with Pin

The secondary host sends a request-control to the primary host. The format for that is `URL: ${SYNC_API_URL}/${namesapceString}

{
   host: 'sttm-web' | 'sunder-gutka' 
   type: 'request-control'
   pin: 1234 
}

Receive Acknowledgement from desktop if pin is correct

{
   host: 'sttm-desktop'
   type: 'response-control'
   success: true | false 
}

Send a Shabad to desktop

When you send a Shabad to desktop, the following will be the format of the data sent that desktop can use with BaniDB API to fetch the required data.

{
   type: 'shabad' // Other options: 'ceremony' | 'bani',
   host: 'sttm-web',
   pin: 1234,
   shabadId: 12, 
   verseId: 1234,
   gurmukhi: 'gurmukhi token of the shabad' // (needed for history store on desktop)
}

Send a Ceremony to desktop

{
   type: 'ceremony' ,
   host: 'sttm-web',
   pin: 1234,
   ceremonyId: 12, 
   verseId: 1234,
}

Send a Bani to desktop

{
   type: 'bani',
   host: 'sttm-web',
   pin: 1234,
   baniId: 12, 
}

Send a verse change to Desktop

{
      host: 'sttm-web',
      type: 'shabad', // or 'ceremony' | 'bani'
      pin: 1234
      ceremonyId: 12, //ceremony ID or null, null when its not a ceremony ID
      baniId: 10, //baniID or null , null when its not a bani ID
      shabadId: 456,
      verseId: 4567,
      lineCount: 123,
}

Why lineCount?

Sometimes in ceremonies or compiled banis, same verse can appear twice a.k.a two verses with the same verseID. At such time the verse ID won't be sufficient to target a unique verse. So we count the line number. The first verse of opened shabad/bani/ceremony has lineCount 1, and 4th verse in a shabad would have lineCount as 4. lineCount increments with each verse in shabad (even if the same verse is repeated twice) which provides us with a unique position of each verse, irrespective of its verseID.

Receive a Shabad from desktop

When you receive a Shabad from desktop, the following will be the format of the data received that you can use with BaniDB API to fetch the required data.

{
        type: 'shabad',
        host: 'sttm-desktop',
        id: ShabadID,
        highlight: LineID,
        homeId: LineID,
        verseChange: false,
}

Receive a Verse Change from desktop

{
        host: 'sttm-desktop',
        type: 'shabad', // or 'bani' or '
        id: 1,
        highlight: 2345,
        verseChange: true,
}

Receive a Bani from Desktop

{
          host: 'sttm-desktop',
          type: 'bani',
          id: 1,
          highlight: 2345,
          baniLength: 'extra-long', // or long | medium | short
          mangalPosition: 'above', // or below
          verseChange: false,
  }

Receive a Ceremony from Desktop

{
          host: 'sttm-desktop',
          type: 'ceremony',
          id: 1,
          highlight: 2345,
          verseChange: false,
}