CowLog is a cross-platform application to code behaviours from video recordings. It can be used in any application where coding behaviours from video is needed. The first version of the application  of was developed in 2009 for a project where we needed to code the sleep behaviour of calves from video recordings in order to develop a sleep actigraph . The software has also been used in several other studies e.g. to study emotions in goats , the mind wandering related to computer use during lectures  and effects of simulated transport on the behaviour of eastern blue tongued lizards . There were 33 papers indexed in Scopus citing the first paper about CowLog  at the time of the writing.
The initial release run only on Linux and had limited configuration options . It soon became clear from our own projects and user feedback from other groups after the initial release that there was a clear need for a cross-platform version.
Two versions of CowLog were developed to address these issues: Python based desktop version and HTML5 application that runs in the browser. Several users were concerned about the privacy issues of the web application although it only used single script to format the output file and everything else run on client side.
The aim of this paper is to describe the implementation of CowLog 3 in order to make it easier for users to modify the program for their needs or participate in development of the released version.
Implementation and architecture
An application implemented using the Electron framework has a main process and one or several renderer processes which display the user interface. The main process, based on Node.js, is used to create the user interface windows, controls the application lifetime and provides features such as file system access and via Node.js modules. The renderer process displays the user interface as a website, each created window runs in its own process.
The renderer process and main process communicate with event based system using the Electron interprocess communication module. An application using Electron can also use almost any Node.js module to extend the functionality.
The used architecture makes the application very modular and the design and implementation in one window can be changed easily without affecting the other windows as long as the messages exchanged between processes are not changed.
The ethogram, folders for videos and output, used video player, modifiers for behaviours and keyboard shortcuts for coding can be defined and modified using CowLog projects. The project settings are saved to JSON file which can be used to transfer the settings between computers and e.g. shared together with publications.
The software makes use of two video players and the user can select the most suitable one for their application:
- VLC player controlled using WebChimera.js, which is able to render video frames directly on HTML5 canvas giving good performance. CowLog binaries on Windows and Mac OS X are bundled with VLC player and precompiled WebChimera.js. On Linux the user should install VLC player separately.
The program supports using multiple videos simultaneously, and all of the videos are played in single window. The playback speed of the video can be changed to make it slower or faster. There is no limit for the number of simultaneous videos used, the practical limitations depends on the capacity of the used computer. In our practical projects we have used at most 3 cameras at the same time to cover large enough area. The layout of the videos is also user selectable.
CowLog user interface for the actual behavioural coding is focused around buttons representing each behaviour. The user can also configure and use keyboard shortcuts for the coding.
Dialogs are used to create and edit projects and starting or resuming coding sessions. Coding buttons and the videos are displayed in separate windows to make it easier to use the software with multiple displays. Figure 1 shows the CowLog main window configured with a simple ethogram to study the behaviour of sows  around farrowing and the video window.
Releases of the software are packaged for different platforms using electron-packager, which makes it simple to package the release for Mac, Windows and Linux architectures with a single command. The Windows version is also released with an installer built using Inno Setup.
The software goes trough functional testing and a beta release before each final release using existing project configurations and several video formats. There are currently no automated tests. The development takes place on Ubuntu Linux, Mac OS X and Windows and the builds are tested on each of the platforms.
The software is used in our own research and we get immediate feedback from users. Several other research groups also use CowLog and have reported from their experiences.
All users can report bugs and ask for features on GitHub or using e-mail.
Windows, 7, 8 and 10. Mac OS X (> = 10.8). Linux 32bit and 64bit, tested on Ubuntu 14.04 and 15.10. Electron runs also on Linux ARM v7, but CowLog has not been tested on that platform.
Additional system requirements
A typical coding session has modest system requirements. The system requirements depend on the codec, resolution and the number of simultaneous videos used. The program can run on all Electron supported platforms.
- – Electron 0.36.2
- – jQuery 2.1.4
- – jQuery UI 1.8.21
- – Bootstrap 3.3.5
- – WebChimera.js 0.1.47
- – VLC player 2.2 (Optional)
List of contributors
- – Dr. Matti Pastell (Natural Resources Institute Finland, Luke). Developer.
- – Dr. Laura Hänninen (University of Helsinki). Requirements for the first version
- – Dr. Andrew Robins (The University of Queensland). CowLog logo, testing and feedback.
Persistent identifier: https://github.com/mpastell/CowLog/releases
Publisher: Matti Pastell
Date published: 13/01/2016 (v 3.0.1)
Date published: 12/09/2015
(3) Reuse potential
CowLog is general purpose application in behavioural coding. It can be used for any project that requires coding the time of events from digital video. The software has been used in studies about animal behaviour as well facial expressions in humans. The software could easily be modified to do also live coding. New developers are welcome to make contribution to the program via GitHub.
The author declares that they have no competing interests.