EasyWorship - Chinese Union Version (Traditional)

Keith Ng
  2024-11-12 2024-11-12 Created   2024-11-20 2024-11-20 Updated  1.1k Words  6 Mins

UPDATE 20/11/2024: A new approach, which allows for the encoding of EasyWorship Bibles from scratch, can be found in my new post

EasyWorship is a popular church presentation software (and the software of choice for my church), but it has a peculiar limitation: it only supports the Chinese Union Version (Simplified) Bible - otherwise known as CUVS, leaving out the Traditional Chinese version (CUV). The Simplified version has been available for nearly a decade, but requests for the Traditional version seem to have been ignored. The EW development team appears to be focused on other priorities, leaving many churches in regions that use Traditional Chinese (e.g. Hong Kong and Taiwan) without a solution other than copying and pasting from other sources.

One potential solution to the issue would be for EW to allow users to import their own Bible translations. However, for some peculiar reason, this wasn’t implemented and they chose to use encode Bible versions which are specifically designed for the software.

I didn’t really want to wait for something that probably wouldn’t end up being delivered - so with some free time on my hands, I decided to try my hand at semi-reverse-engineering their EWB files, which as their name suggests, stores EasyWorship Bibles. The result of a night’s work is a Python script which takes the existing CUVS Bible, converts the Simplified Chinese characters into Traditional Chinese characters, then re-encodes it into the EWB format as an add-in Bible. We are using the opencc-python-reimplemented library to convert from Simplified to Traditional characters

The new EWB format is just an SQLite database, with Bible verses being stored as ZLib compressed data in a blob per book. This made it easy to modify CUVS to CUV - the main challenge was to get EW to recognise this was a new add-in Bible, which took some time poking through the hex values everywhere.

Quick summary:

  1. Go through the ‘stream’ table, using ZLib decompression to extract the text for each book, OpenCC to convert from SC to TC, then compressing this new TC text using ZLib
  2. Go through the ‘books’ table, using OpenCC to convert the book name from SC to TC, and updating the pointers in the ‘verse_info’ attribute to point to our new Bible. This is done so that EW knows what text belongs to which verse in this specific Bible translation
  3. Go through the ‘words’ table, using OpenCC to convert each word from SC to TC. This table appears to be used for searching for Bible verses by characters or words
  4. Set the new Bible ID and name in the ‘header’ table so EW knows what Bible translation this is

I won’t distribute this modified Bible translation here, but you can find the script to generate your own CUV (Traditional) EW Bible below. You can find the necessary EWB files on the EW website. Hopefully someone is able to also reverse-engineer the data stored in the ‘verse_info’ attributes, which would allow for custom encoding of EW Bible translations and eliminate the need to wait (forever) for Bible requests to be implemented. Note: the ‘book_info’ attribute in the ‘books’ table seems to be the same for each book in every Bible translation - I assume it only stores information such as amount of chapters and verses, which would make sense as this type of data wouldn’t change across Bible translations.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import sqlite3
import zlib
from opencc import OpenCC

converter = OpenCC('s2t')
conn = sqlite3.connect('CUV.ewb')
cursor = conn.cursor()

# Stream update (actual bible verses)
cursor.execute("SELECT rowid, stream FROM streams")
rows = cursor.fetchall()
for row in rows:
    compressed_blob = row[1]

    decompressed_data = zlib.decompress(compressed_blob)
    decompressed_text = decompressed_data.decode('utf-8')

    converted_text = converter.convert(decompressed_text)
    compressed_data = zlib.compress(converted_text.encode('utf-8'), level=9) + compressed_blob[-10:]

    cursor.execute("UPDATE streams SET stream = ? WHERE rowid = ?", (compressed_data, row[0]))

# Book name and bible ID update
def overwrite_bible_id(byte_data, new_byte):
    modified_bytes = []
    for i in range(0, len(byte_data), 8):
        chunk = byte_data[i:i + 8]
        if len(chunk) == 8:
            chunk = chunk[:-1] + bytes([new_byte])
        modified_bytes.extend(chunk)

    return bytes(modified_bytes)

cursor.execute("SELECT rowid, name, verse_info FROM books")
rows = cursor.fetchall()
for row in rows:
    new_name = converter.convert(row[1])
    # 0xFE = 254 = 2 * 127 (127: bible ID)
    # Increment 1 starting from 3 John book (why???)
    new_verse_info = overwrite_bible_id(row[2], 0xFF if row[0] >= 64 else 0xFE)

    cursor.execute("UPDATE books SET name = ?, verse_info = ? WHERE rowid = ?", (new_name, new_verse_info, row[0]))

# Word update (in-text searching for verses)
cursor.execute("SELECT rowid, word FROM words")
rows = cursor.fetchall()
for row in rows:
    cursor.execute("UPDATE words SET word = ? WHERE rowid = ?", (converter.convert(row[1]), row[0]))

# Set bible ID and name
cursor.execute("UPDATE header SET id = 127, name = 'Chinese Union Version (Traditional)', abbrev_name = 'CUV'")

conn.commit()
conn.close()

There also appears to be an issue with the existing CUVS Bible. The character ‘冇’ is encoded as ‘有’ throughout the entire Bible translation - a quick search through the CUVS reveals that this character does not appear at all in the CUV and confirms this is a genuine error. A pretty major oversight at that - ‘冇’ essentially means the exact opposite of ‘有’ (‘to not have’ vs ‘to have’)

Nothing that a script can’t fix though - here’s one to make the necessary corrections, which you should probably run before converting CUVS to CUV (Traditional). If there happens to be more discovered and confirmed, you can always add it to the dictionary and re-run the script!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import sqlite3
import zlib

characters = {
    # Old: New
    '冇': '有'
}

conn = sqlite3.connect('CUVS.ewb')
cursor = conn.cursor()

cursor.execute("SELECT rowid, stream FROM streams")
rows = cursor.fetchall()
for row in rows:
    compressed_blob = row[1]

    decompressed_data = zlib.decompress(compressed_blob)
    decompressed_text = decompressed_data.decode('utf-8')

    new_text = ''.join(characters.get(char, char) for char in decompressed_text)
    compressed_data = zlib.compress(new_text.encode('utf-8'), level=9) + compressed_blob[-10:]

    cursor.execute("UPDATE streams SET stream = ? WHERE rowid = ?", (compressed_data, row[0]))

for old_character, new_character in characters.items():
    cursor.execute("UPDATE words SET word = ? WHERE word = ?", (new_character, old_character))

conn.commit()
conn.close()
Recommended
Custom Bibles for EasyWorship Custom Bibles for EasyWorship Taking out backgrounds behind text Taking out backgrounds behind text Azure AD, AAD DS & RADIUS (NPS) Azure AD, AAD DS & RADIUS (NPS)
Recommended
Custom Bibles for EasyWorship Custom Bibles for EasyWorship Taking out backgrounds behind text Taking out backgrounds behind text
Comments
On this page
EasyWorship - Chinese Union Version (Traditional)