SooSL program and project files (D)

Miscellaneous ››
Parent Previous Next

This help topic is more technical. Most people can ignore it. This topic is for people who want to know more about how SooSL stores information on their computer.

SooSL settings file

SooSL keeps a settings file. This is where SooSL remembers things about how you use SooSL on your computer. It remembers things like window size, fonts, keyboards, the last dictionary you had open, etc. This type of information is not stored with individual dictionaries. It applies to all your dictionaries.

The normal location for this file is:

You can edit this file with a text editor if you are careful. (Make a spare copy first!) Some of it is cryptic; if you don't understand something, leave it alone. 

Over time, the soosl.ini file fills up with junk data. Sometimes this can make SooSL behave strangely. If this happens, try renaming the soosl.ini file to some other name. SooSL will then start over with a new set of settings. You'll have to set things up again, such as how you have your screen arranged. That doesn't take very long. If you want to go back to your old settings, just rename the old file back to "soosl.ini".

The user's SooSL folder: log files, default location of dictionary projects and ZooZL files

SooSL Desktop creates a folder (directory) called SooSL with your user files. The exact location depends on your computer. Typical locations are:

SooSL keeps its log files in the SooSL folder. If SooSL is not working right, there may be information in these log files that will help you identify the problem. Even if you don't understand them, you can send them to us when you contact us.

Along with the log files, the SooSL folder also contains three sub-folders:

These are the default locations for dictionary projects and ZooZL files. However, you can store dictionary project files and ZooZL files any place on your computer. You can use the special SooSL file dialogs for Open dictionary, Import dictionary, Export dictionary and Delete dictionary to access SooSL files in any folder on your computer. You can even use a folder on another computer through a local area network (LAN)

Sub-folders inside SooSL dictionary projects

SooSL stores its files inside the folder for the dictionary project:

<__name__ >                   project folder

<__name__ >.json         main JSON file (information about the whole project)

_signs                         folder with files for the signs themselves, both JSON files for written information and video files



_sentences                 folder with video files for example sentences


_extra_videos                 folder with extra videos


_extra_pictures         folder with extra images

*.jpg, *.png, etc.

(This organization is for version 0.9.2 and later. In versions 0.9.1 and earlier, the sub-folder names were the same, but without the initial underline. We made the change to protect data from a nasty bug in earlier versions.)

The <__name__> of the main JSON file for the project is the same as the <__name__> of the project folder. Usually, it is similar to the name of the dictionary.

Filenames of video and image files are the same as your original filenames, except that:

(In version 0.9.2 and later, each sign has a a JSON file and video file. The JSON file includes the written information about each sign. The two files have the same filename, but with different extensions: .json vs. .mp4. In versions 0.9.0 and 0.9.1, all the written information about signs was in the project JSON file; not in individual JSON files for each sign. We reorganized in version 0.9.2 to make it possible for more than one user to work on the same dictionary at the same time. In version 0.8.x and earlier, the written information about signs was in an SQLite file. We stopped using SQLite to integrate better with SooSL Web.)

File formats inside dictionary projects

SooSL uses these file formats inside a dictionary project:

JSON text files (.json)

JSON files are human-readable text files. In version 0.9.2 and later, there is one JSON file with information about the whole project, and individual JSON files for each sign.

You can edit them manually with a text editor if you are careful. Do this at your own risk. Before you do, learn about JSON file format and study the details of SooSL's JSON files to make sure you understand them. 

We recommend you make a spare copy of the whole project before trying to edit any JSON files manually. That way, if your changes don't work, you can recover your project. You should make a spare copy of the whole project, including all the video and image files, because some changes can trigger other changes the next time you open SooSL, including deleting files. The easiest way to do this is to export the dictionary project to a ZooZL file.

Don't change anything you don't understand. Especially, don't change timestamps or hashes, because they need to be left alone for SooSL to work properly. Be very careful about changing ID numbers.

If you rename video or image files in a project, you will also need to change the references to them inside the JSON file(s) for the signs that use those videos or images. 

Videos (.mp4)

SooSL converts videos to reduce the file size (it transcodes them with ffmpeg). It sometimes reduces the resolution. This is okay, because SooSL does not need to display the videos at a large size. It always uses moderate compression and quality settings. Smaller video files save storage space on the computer, they make ZooZL files smaller for transferring between computers, and they make SooSL Web run faster. The size of the videos determines the size of the whole project; other files take up relatively little space. (See this help topic to estimate how much hard disk space you will need for a project.)

Images (.jpg, .png, and others)

SooSL leaves images in the original format you provide. This means that you should start with standard image file formats that are widely-supported. We recommend JPG (.jpg) for photos and PNG (.png) for all other images.

ZooZL file structure

When you export a dictionary project, SooSL packs all the files into a single ZooZL file. This is actually a standard ZIP file, except it has a .zoozl extension instead of .zip. You can change the extension from .zoozl to .zip and uncompress it if you want. That is what SooSL does when it imports the ZooZL file.

Inside a ZooZL file, the files and sub-folders are the same as for dictionaries in version 0.9.2, except

This structure inside ZooZL files from version 0.9.2 and later is basically the same as what SooSL used in active dictionary projects and ZooZL files for versions 0.9.0 and 0.9.1. The only difference is that 0.9.2 ZooZL files include the inventory file. 

Compatibility between versions

ZooZL files created by version 0.9.2 and newer are "backward compatible" to version 0.9.0. This means you can import them if necessary into any 0.9.x version. You can send a ZooZL file created with version 0.9.2 to someone who has an earlier 0.9.x version, and they should be able to import it. 

However, we recommend that you always use the newest version of SooSL Desktop. It has fixed many bugs and includes many new features. So, it is better if the person receiving the ZooZL file upgrades to SooSL Desktop version 0.9.2 before trying to import it.

You cannot import ZooZL files from versions 0.9.x into older versions of SooSL (versions 0.8.x and earlier). However, you can import ZooZL files from versions 0.8.x into versions 0.9.x. SooSL will convert the information in them to the newer format. After that, you must use the newer versions to edit the dictionary projects. You can no longer open them in the older versions.

For active projects, compatibility is only reliably in one direction. Newer versions of SooSL can read older dictionary projects. This happens when you upgrade SooSL from one version to a later version. It might also happen if you move a dictionary project from one computer to another without creating a ZooZL file, but just copying all the project files. When the newer version of SooSL opens a dictionary project that was created with an older version, it converts the project to the newer version. After that, you must use the new version to read and change the dictionary. You can no longer open it in the older version.

In a few cases, some older versions of SooSL can read dictionaries created by some newer versions. However, most of the time you will need to use the version that last opened the dictionary, or a newer version. If SooSL cannot open a dictionary because it is in a newer format, it will tell you what version of SooSL you need to open it. 

Created with the Personal Edition of HelpNDoc: Easily create EPub books