This guideline explains how to register for an account at the READ-COOP-homepage (https://readcoop.eu/) and how to download, install and run the Transkribus expert client. Information on how to transcribe documents with Transkribus you can find in the 10 steps guideline and in How to Transcribe Documents with Transkribus – Introduction.
Download the Transkribus Expert Client, or make sure you are using the latest version here.
Registration
- To work with Transkribus, you need to register for an account at https://readcoop.eu/
- To register, click on “Sign in” and then on “Register”. You will need to provide your name, e-mail address, and accept the Transkribus user agreement.
- According to Austrian data protection law, we will respect your privacy and use your data only to improve our services and support research in humanities and computer science.
- If you need to change your password, you can find the option to reset it by clicking on “Sign in” and then “Forgot Password?”.
- If you want to delete your account, please send a message to: info@readcoop.eu
Download and installation
- Once you have registered for an account, you can download Transkribus for free from our homepage.
- Whereas all the other functionalities of Transkribus can be used for free, for the automated transcriptions credits are needed. All the information on the credit system you can find here.
- Every new Transkribus account gets 500 credits for free to do some testing. Moreover, with this we want to support those with small transcription projects, who need to recognise a few pages only.
Supported Operating Systems
- Transkribus runs on Windows, Mac and Linux. It is written in Java. Please make sure you have a 64-bit version of Java installed on your computer that is not older than Java 11 for Transkribus to work. You can download it from here: https://www.oracle.com/java/technologies/downloads/
Transkribus requires Windows 64 bit. If Transkribus does not start, it may be because a 32 bit operating system is installed. Then a new 64 bit operating system would have to be installed.
How can this be found out?
1. go to Windows Settings – About
2. or run Transkribus from the console to get a more detailed error message:
a. To do this, type ‘cmd’ in the Windows search, open the ‘Command Prompt’. Then change to the Transkribus folder with cd ‘Transkribus directory’ (e.g. cd C:UsersUsernameTranskribus-1.17.0) and run ‘java -jar Transkribus.exe’.
In case of Java problems, the Java package can also be copied directly into the Transkribus folder. The Java package must be renamed to ‘jre’, so that Transkribus then uses this Java.
To find out the Java version on your own computer, start the console again and type java -version. Then the current version will be displayed. If no java version is displayed, then the operating system cannot (yet) find the installed Java. Then a reboot or setting the ‘PATH’ variable can help: https://michster.de/wie-setze-ich-die-path-umgebungsvariablen-unter-windows-10/
Unzip ZIP File
- After clicking on the download button on the READ-COOP-homepage you will get a ZIP-file, which you will need to unpack (right click on the folder then choose “Extract all”).
- Open the Transkribus directory. There you will find the executable files for your operating system.
- Then double click the .exe-file for Windows, the .command-file for Mac or the .sh-file for Linux to start the installation.
Notes for first launch on Linux
- If the OS is based on Ubuntu 17.04, installing libwebkit is necessary: sudo apt install libwebkitgtk-1.0-0
Notes for first launch on Windows
- If you do not have “Administrator” rights, Windows will produce a warning message, such as: Your Computer is Protected by Windows”, etc.
- Do not confirm, instead open “More Information” and confirm that you want to run Transkribus anyway.
Notes for first launch on MAC
- If you run the program the first time, it may not start because it is a non-signed application (“… can’t be opened because it is from an unidentified developer” message)
- In this case, right-click (or control-click) the application and choose “Open”. In the appearing dialog box, click “Open” again.
- Alternatively, right click the Track Pad to open the Context Menu and add a security exception for Transkribus.
- Another option: right-click on the program icon -> Open (in the context menu) -> via Terminal.
- If the app won’t start at all
- You can try to move the application out of the Download folder, i.e. copy or move it to another destination folder like the Desktop.
- Error message when trying to start the app from a terminal using open -a Transkribus.app is: LSOpenURLsWithRole() failed for the application /Users/xxx/Desktop/Transkribus.app with error -10810.
- A workaround for starting the program anyhow until then is to start a new terminal (search for ‘terminal’ after hitting cmd + space), then cd into the directory where Transkribus was unpacked, e.g. the ‘Downloads’ directory:
- Then start the program directly from the start script that is included in the Transkribus.app package:
- ./Transkribus.app/Contents/MacOS/Transkribus
Run Transkribus
Run Transkribus via command line
- Transkribus is contained in the main jar file Transkribus-<version>.jar
- To run the program from command line type: java -jar Transkribus-<version>.jar
- Note: Java 11 or one of the following versions is needed.
- Some problems (mainly Java heap space) occur because a Java 32 bit version is installed on a 64 bit operating system.
- Note: To run the scripts in Mac (or Linux) you may have to make them executable from the command line: (any version before 0.6.8)
- Mac console basics
- change into the program folder using ‘cd’ commands
- chmod +x Transkribus.command (or chmod +x Transkribus.sh for Linux!)
- Furthermore, you will find several files in the Transkribus package copied to your computer:
- config.properties can be modified to adjust simple appearance properties
- virtualKeyboards.xml can be used to specify a set of virtual keyboards
- logback.xml can be modified to adjust logging properties (for expert users only)
- The ‘libs’ subfolder contains the necessary libraries for all platforms. Currently supported are:
- Windows 32/64 bit
- Linux 32/64 bit
- OSX 64 bit
Using a proxy server
- If you keep getting the error message “Login failed: already connected” the problem can be the proxy server.
- When the program has started, click on the home menu button on the top left and select “Proxy settings…”. In the following dialog you can set the proxy host, port, user name (optional) and password (optional). This is the recommended method for using a proxy server.
- Alternatively, you can edit the start script (e.g. Transkribus.bat on Windows, Transkribus.sh on Linux) to include the environment variables for the proxy server:
java -Dhttps.proxyHost=<proxyserver>
-Dhttps.proxyPort=<proxyPort>
-Dhttps.proxyUser=<user name for proxy>
-Dhttps.proxyPassword=<password for proxy>
-jar Transkribus-0.14.0.jar
However, editing this file will be necessary on each update of Transkribus.
Known Issues
Logging in to the server is not possible via Transkribus, but on the website it works.
- Another possible reason for the error message “Already connected”: your Java installation may be outdated and can’t establish a secure connection to the server. You can check your installed version by opening a terminal/command line and entering “java -version”. If you encounter this problem, try updating Java on your machine. We recommend a current version not older than Java 11 (Oracle or OpenJdk). The Mac version of Transkribus includes a Java runtime. If you encounter this problem on a Mac please download a new package from https://readcoop.eu/ and update your installation. If the error persists please contact info@readcoop.eu, ideally including the log file of your installation (from the Transkribus directory: logs/TrpGui.log) and/or information on your Java version and operating system.
- Note: the Mac version of the expert client comes with a java shipped within the application. If this java version is outdated, you can try to delete or replace it with an updated version. To find the files in Mac finder, right-click (or cmd-click) on the Transkribus application in your programs view, click “show packages contents” in the context menu, then go to the subfolder “Contents/MacOS”. There, the subfolder “jre” contains that java version. If you delete this folder, the application starter will try to find java on your system.
- You may have to configure a proxy server via ‘main menu’ – ‘Proxy settings’.
Wrong JAVA Version on Mac
- After opening the command file on the Mac, Transkribus says that there is a wrong Java version installed. However, there is the most current version of Java installed.
- The problem is that an older version may still be installed and set as default Java. You can check the default version by opening the terminal and typing ‘java -version’.
- To solve the problem you can either download the latest jdk as a .tar.gz package from here:
https://www.oracle.com/java/technologies/downloads/
and unpack it into the Transkribus folder – the Transkribus.command file will automatically check for java installations in its sub directories.
- Alternatively you can try to set your Java 11 (or one of the following versions) installation as default one in the command line following e.g. the instructions here:
http://myshittycode.com/2014/03/17/mac-os-x-setting-default-java-version/
Java Heap space / No more handles
- 32 bit Java on a 64 bit Windows OS -> install 64 bit Java from here: https://www.oracle.com/java/technologies/downloads/
- Too little RAM: Try to allocate more main memory by opening Transkribus.bat and set e.g. java -Xmx2048m -jar Transkribus-1.14.0.jar
- Start Transkribus with this bat file
Logging in is prevented by the Firewall of your Internet Provider
- Some IT departments are blocking the SSL port 443 and/or unknown applications via a firewall. Please check with your IT department if that might be the case.
Avira or Norton Antivirus detects a threat and is blocking the zip file from being unpacked.
- Solution: This is a false alarm which Norton gives when encountering software it is not familiar with (WS.Reputation.1). You should be able to restore the file from quarantine by following the instructions from the following resource [1].
Transkribus does not start on (Fedora) Linux – ‘MOZILLA_FIVE_HOME not set’ error message
- The package “libwebkitgtk” may not be installed. On Fedora you can install the package using dnf on the command line (use “yum” instead of “dnf” in older versions of Fedora): sudo dnf install webkitgtk
Dark mode on Mac
- The dark mode on a Mac can sometimes cause problems with Transkribus, so if Transkribus does not run properly on your Mac and you have the dark mode switched on, please try to turn it off. You might need to reinstall Transkribus after turning off the dark mode in order to take the change into effect.
Credits
We would like to thank the many users who have contributed their feedback to help improve the Transkribus software.
The Transkribus Platform is provided by the European Cooperative READ-COOP SCE.
Until June 2019 Transkribus was financed as part of the Horizon 2020 READ-project under grant agreement No. 674943.
