SooSL program and project files (D)
This help topic is more technical. Most people can ignore it. This topic is for people who want to know more about how SooSL Desktop stores information on their computer.
SooSL keeps a settings file. It keeps track of how you use SooSL on your computer. It records things like window size, fonts, keyboards, the last dictionary you had open, etc. It applies to all your dictionaries and how you use them on a single computer.
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 coded and hard to understand; 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 in a new soosl.in file. 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".
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. They can help us figure out the problem.
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).
SooSL stores its files inside the folder (directory) 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
*.json
*.mp4
_sentences ← folder with video files for example sentences
*.mp4
_extra_videos ← folder with extra videos
*.mp4
_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, the name is similar to the title of the dictionary, but not identical. It is often identical to the Project ID that SooSL assigns to the dictionary when you first create it.
file names of video and image files are the same as your original file names, except that:
Every dictionary project has three identifiers:
The folder name is used to identify the project on the computer's hard drive. This is the folder where all the files for the dictionary are stored. The folder name is also used in the JSON file name. These two should always be the same. If you rename one, you should rename the other also; otherwise, SooSL will not recognize that the folder contains a SooSL dictionary and will not open it.
Similarly, an exported ZooZL file has a file name, which is often the same as the folder name that it was exported from, or similar to it.
The title is a friendly name that is shown in the SooSL Desktop title bar and in the general information about a dictionary. It is intended for use by people. When you publish a dictionary on SooSL Web, this is the name that is shown to users. You can easily change it by choosing About dictionary from the 
Tools menu, and then clicking Edit. It is stored in the main JSON file for the project.
Every dictionary project also has a unique Project ID. SooSL assigns the Project ID when it first creates a new dictionary, based on the dictionary's first title and the time it was created. You can see a dictionary's project ID in the general information about a dictionary. SooSL uses it to identify which dictionary projects are different versions of the same dictionary. This is important when you import, export and upload files.
The Project ID is stored inside the project's main JSON file. Often it is also used as the name of the project's folder and main JSON file and for the name of exported ZooZL files. You may use a different name for the folder and JSON file and for ZooZL files if you want. However, do not change the Project ID inside the JSON file, or you will make it impossible for SooSL to recognize other versions of the same dictionary.
SooSL uses these file formats inside a dictionary project:
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, plus 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 (backup) 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, because each sign must have a unique ID number and ID numbers are also used in SooSL's internal copies of videos and images.
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.
SooSL converts videos to reduce the file size. (It converts them with ffmpeg, so your original videos can be in any format that ffmpeg recognizes.) SooSL 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 total size of the videos is the main factor determining 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.)
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. These two formats are supported in all operating systems used by SooSL. Other file formats may not work when you move a dictionary project to another operating system or publish it on SooSL Web.
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 and it has a special internal folder (directory) structure. 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 in the project folder 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 ZooZL files from version 0.9.2 and later include the inventory file. This provides limited backwards compatibility.
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 reliable 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