Manual

This Manual describes every menu item, tool, button, and option in Korsakow 5.0. See also the Quick Start guide, the FAQs, Tips & Tricks, and the basic video Tutorials.

NOTE

In this Manual, the ‘user’ is the person using the Korsakow System to make a Korsakow Film. The ‘viewer’ is the person viewing the completed Korsakow Film in a web browser such as Chrome, Firefox, Safari, or Internet Explorer.


Contents

  1. Top Level Menus
    1. File
      1. File > Project Settings
    2. Edit
    3. Tools
    4. Language
    5. Help
  2. SNU Editor
  3. Interface Editor
  4. Adding Subtitles
  5. Viewing a Korsakow Film

1.0 Top Level Menus

NB The Top Level Menus appear at the top of the Korsakow application main window.

Korsakow application main window

This is the central project window through which all Korsakow Films are organized and edited, prior to Export. The main window lists all the media assets assembled (via drag-and-drop) for a Korsakow project, and provides access to the SNU Editor and the Interface Editor. The main window can be resized by dragging the bottom righthand corner.

The list of media assets can be organized in several different ways, by clicking on the column headers (eg Name, Type, Lives, etc). For example, since the default order is alphabetical, descending, clicking on the header at the top of the ‘Name’ column will reorganize the entire list alphabetically, ascending. Click on the header again to reverse the order. Click on the ‘Type’ header to organize everything according to the type of media, and so on. The columns can also be rearranged by clicking and dragging any header to a new position to the left or right of its current position.

For a larger project, folders can be created and nested to help organize all the media assets. To create a new folder, click on the New Folder icon in the bottom righthand corner of the main window. Rename the new folder, and drag some of the media assets into it.

Double-clicking on any media asset except an interface or a sound file will open up the SNU Editor for that media file. Double-clicking on an interface will open up the Interface Editor.


1.1 FILE

File > New

Begin a new Korsakow project.

File > Open

Open an existing Korsakow project (.krw file).

File > Recent

A shortcut to open a Korsakow project (.krw file) that you have recently worked on.

File > Save

Save all changes made to the current Korsakow project (.krw file). Makes an audible confirmation when used. Use this regularly to avoid losing work! NB There is no Autosave function as yet.

File > Save As

Save an existing Korsakow project (.krw file) with a new name and/or in a new location.

File > Import > Version 3 Project

Import a Korsakow project created in Version 3. Navigate to, and then select, the database.txt file for that project.

File > Import > Shared Interface

Korsakow Interfaces are the layouts of SNU and Preview widgets visible in the web browser during the playing of a Korsakow film. (The Default Interface is three small Preview widgets evenly spaced under one large SNU widget.) Use this menu option to import an existing Interface (.kif file) that is not already in the current project – perhaps designed by you for another project or shared with you by another Korsakow filmmaker. (Must be exported from the other project as a .kif first.)

File > Export > For Web

Exports the current Korsakow project for playing in a web browser (e.g. Chrome, Firefox, Safari). Creates an index.html file and an associated data folder. To view the project, open the index.html file using any web browser. To view Korsakow films online, the index.html file and data folder must be uploaded to the same directory on a web server using an FTP client (e.g. WS_FTP, Fetch, Transmit) after Exporting. (We have a service to provide webspace for this purpose.)

File > Export > Draft for Web

Removed in version 5.1.

File > Export > Shared Interface

Users can share Interfaces that have been created using the Interface Editor (accessible by double-clicking on any existing interface file in the Korsakow application main window, or clicking on the ‘New Interface’ icon in the bottom right corner of the main window). Select the interface to be exported, then go File > Export > Shared Interface.

File > Project Settings. See below:


1.1.1 The Project Settings Dialog

The Project Settings dialog box (File > Project Settings) offers several settings, and is divided between three tabs, Movie, Export, and Workspace, as follows:

Movie tab

Name

This is the Project name. It will appear in the Korsakow application main window and, after the film is exported, in the title bar of any web browser that plays the Korsakow film.

Movie Size

The overall dimensions of the project in the web browser.

Click Sound

Optional. The audio cue heard by the viewer when clicking on a Preview widget. The sound file providing this cue must be dragged and dropped into the Korsakow application main window before it will appear in the Click Sound pulldown menu. The sound file should be in .wav or .mp3 format; other formats may work. To the right of the pulldown menu is an independent volume control for the Click Sound. NB Poorly chosen Click Sounds can be intrusive and easily detract from the viewing experience.

Default Background Sound

Optional. The audio heard by the viewer during the entire Korsakow film. The sound file providing this audio must be dragged and dropped into the Korsakow application main window before it will appear in the Default Background Sound pulldown menu. Can be turned off, paused, or changed for a particular SNU during SNUifying.

Default Background Image

Optional. The image seen in the background of the browser window. The image file must be dragged and dropped into the Korsakow application main window before it will appear in the Default Background Image pulldown menu. The default is a plain black background. This colour can be changed by clicking on the ‘Color’ button. Click on the red Delete button to return to the default plain black background.

Start Screen

Optional. The initial static image that appears at the beginning of a Korsakow film. Often used for the title, production credits, etc. The viewer clicks on the Start Screen to dismiss it and start the Korsakow film. The image file must be dragged and dropped into the Korsakow application main window before it will appear in the Start Screen pulldown menu.

Maximum Links

Advanced setting. Optional. Defines the maximum number of links a search of a keyword-line can trigger. This project setting can be overwritten by each keyword-line individually in the SNU Editor.

Random Link

Advanced setting. Optional. If Korsakow is not able to find any links based on keywords, Random Link offers up a random SNU – but only if there are still some SNUs left to play (ie SNUs with one or more lives left).

Keep Links

Advanced setting. Optional. Korsakow film demonstration here. If Korsakow is not able to find any links based on keywords, Keep Links displays the links of the previously played SNU, minus the last one clicked – but only if there are still some SNUs left to play (ie SNUs with one or more lives left).

Export tab

Compress Video

Removed in version 5.1. For detailed guidelines regarding video compression, see Tips & Tricks.

Encoding profile

Removed in version 5.1. For detailed guidelines regarding video compression, see Tips & Tricks.

Workspace tab

Adjust file paths

Advanced feature. Provides four options for saving project files as relative or absolute paths. If in doubt, leave this feature in its default setting, ie Smart Adjust.

Experimental Features

Advanced feature. Check this box to enable the use of Korsakow’s experimental widgets in the interface editor. NB Experimental widgets are unsupported. We suggest using one at a time, and testing as you go.

List Similarly Named Resources First

Advanced feature. Check the box to list similarly named resources first within the SNU editor. We recommend leaving this option selected.

 


1.2 EDIT

Edit > Duplicate

Makes an exact copy of any item in the Korsakow application main window. Short cut: Right-click (PC) or Ctrl-click (Mac) on the media asset and select ‘Duplicate’.

Edit > Delete

Deletes any item in the Korsakow application main window. (See also the Delete button in the bottom righthand corner of the Korsakow application main window.) Short cut: Right-click (PC) or Ctrl-click (Mac) on the media asset and hit ‘Delete’ on your keyboard.

NB The icons at the bottom right corner of the Korsakow application main window provide some Editing functionality:

New SNU

Click to create a new SNU from an existing media asset in the Korsakow application main window. The media asset must be selected first. Opens up the SNU editor. (Double-clicking on a media asset in the Korsakow application main window will also open up the SNU editor.) Short cut: Right-click (PC) or Ctrl-click (Mac) on the media asset and select ‘Create SNU’.

New Interface

Opens the Interface Editor. Double-clicking on an existing interface listed in the Korsakow application main window will also open the Interface Editor.

New Folder

Creates a ‘virtual’ folder allowing the user to organize any number of items in the Korsakow application main window. Using these folders does not actually move any of the files on the user’s harddrive. There is no limit to the number of folders, and folders can be nested inside one another. Double-click on a Folder’s icon in the Korsakow application main window to open it and examine its contents. Double-click it again to close it.

Rename

Allows the user to name or rename a virtual folder. Short cut: Right-click (PC) or Ctrl-click (Mac) on the virtual folder and select ‘Rename’.

Delete

Selecting any single item in the Korsakow application main window and clicking the Delete icon will remove it from the current project. To select more than one item use the Command key or Shift key. Short cut: Right-click (PC) or Ctrl-click (Mac) on the media asset and select ‘Delete’. Media assets will be removed from the project but not deleted from the user’s harddrive.

 


1.3 TOOLS

All of the Tools are floating windows providing extra information about the Korsakow film being made. They do not need to be open for Korsakow to work.

Tools > All Keywords

All Keywords Tool

All Keywords Tool

Lists all Keywords in the current project. Keywords are used when SNUifying. Each Keyword has a score, shown to its left, indicating how many times it has been used as an ‘In’ (i.e. “I am…”) Keyword and as an ‘Out’ (i.e. “I am looking for…”) Keyword. These are indicated using a red cube (In) and a blue cube (Out). These icons can also be seen in the SNU Editor. Double-clicking on a Keyword in the All Keywords Tool window while SNUifying will add that Keyword to the In and Out fields of the SNU. (Note that more than one SNU Editor can be open at once but only one can be selected at a time; this change only applies to the one that has been selected). Clicking on just the ‘In’ column of the Keyword in the All Keywords Tool window will add that Keyword only to the In field of that SNU. Clicking on just the ‘Out’ column of the Keyword in the All Keywords Tool window will add that Keyword only to the Out field of that SNU. This shortcut means that the user only has to type in each Keyword once for the entire project. Clicking on the small black triangle to the right of the Keyword reveals exactly which SNUs are using the Keyword and in what way.

Tools > All SNUs

Lists all SNUs in the current project. Clicking on the black triangle on the righthand side reveals the In and Out Keywords being used in that SNU.

Tools > All Links

Lists all SNUs in the current project. Shows the other SNUs linked to each SNU. SNUs are linked to one another via shared Keywords.

Tools > Unused Media

Lists the Media that have not been used as SNUs. Also includes Previews.


1.4 LANGUAGE

The application was built in English, but users are encouraged to help us expand Korsakow’s accessibility by providing different language translations. So far we have French, Hebrew, Portuguese, Spanish, and German. Select the preferred translation and restart Korsakow to activate it.


1.5 HELP

Help > Load Example

To help new users understand how Korsakow works, the application includes a simple, but complete, Korsakow film called Circle of Life. New users should try loading this project, exploring the way it was made (especially the SNUs and the Interface), and then exporting it. We recommend doing this without making any changes, at least on the first try. After that, make one change at a time to see how it affects the Exported film.

Help > Show Log

If something goes wrong, Korsakow automatically creates an error log. The error log is a text file called ‘korsakow.log’. It can be retrieved and viewed by selecting ‘Show Log’.

Help > Korsakow Homepage

A direct link to the Korsakow project website. Selecting this option will open your default browser and take you to www.korsakow.org


2.0 SNU Editor

SNU Editor

The SNU Editor is for SNUifying media assets. The SNU Editor can be opened in three ways: 1) double-click on a media asset (video or still image) in the Korsakow application main window, or 2) select a media asset and then click on the ‘New SNU’ icon in the bottom righthand corner of the main window, or 3) right-click on the media asset.

From top to bottom:

SNU Name

The textbox at the top is for naming (or renaming) the SNU, to help with keeping a project organized. The default name matches the name of the media asset. Giving the SNU a new name will not change the name of the associated media on the user’s harddrive.

Media Player

Below the textbox is a window for previewing the media asset that is being SNUified. This includes a play/pause button and a timeline scrubber which can be dragged back and forth.

Settings

Start SNU

One or more SNUs should be selected as the first SNU to play, otherwise the film will start from a random point. If there is more than one start-SNU, one of them will be chosen at random.

End SNU

Optional. One or more SNUs can be selected as the last SNU to play. The End-SNU is often used for the final credits in a Korsakow film.

Loop

Optional. If this box is checked, the current SNU will keep playing over and over until the viewer clicks on the preview for another SNU. While the media itself loops, the keyword rules are only triggered the first time through.

Insert text

Optional. Any text placed here will appear in the Korsakow film when this SNU plays. It requires the Insert Text widget, which must be added to the Interface associated with this SNU using the Interface editor. The widget can be placed on top of other widgets, if desired.

Lives

Controls how many times the SNU can appear during one viewing of the Korsakow film. For no restrictions, select ‘infinite’. Default setting is one life.

Interface

Select the interface design to be used when this SNU plays. By default the Default Interface is selected.

Background sound

Optional. Sound(s) to be played during the SNU. Any audio files already in the Korsakow application main window will appear here in the pulldown menu. Only one file can be selected as the background sound for any given SNU.

SNU Rating

Advanced feature. Optional. Korsakow film demonstration here. This refers to the chances of a SNU being selected, assuming there are more available in a given moment than the number of Preview widgets will allow. The SNU rating can be altered or weighted using the SNU Rating slider. This feature adds an intentional bias into otherwise random selections. Can be left at 1.00.

Keywords (see also Tools > All Keywords)

Keywords are the DNA of a Korsakow Project. ‘IN’ Keywords (indicated by the red cube icon) describe the content and/or the meaning at any given moment in the SNU being edited in the SNU Editor, and can be thought of as “I am…” statements. ‘OUT’ Keywords (indicated by the blue cube icon) tell Korsakow how to find SNUs with matching ‘IN’ Keywords while the Korsakow film is playing, and can be thought of as “I am looking for…” statements. Korsakow can also be told when to activate its OUT (ie “Looking for…”) Keywords using the Time column in conjunction with the video scrubber.

  • IN Keywords can be added by typing in the IN textbox (red when selected), and using commas or spaces between each one. Do not use unusual characters such as $ or ß or ü in the keyword names. NB Spaces at the beginning or end of keywords are automatically removed.
  • OUT Keywords can be added by typing in the OUT textbox (blue when selected). Do not use unusual characters for your keywords. NB Spaces at the beginning or end of keywords are automatically removed. The Time associated with each OUT Keyword (shown in seconds and milliseconds) is the point at which it is triggered during the playing of the SNU. The default is 0.00 secs, meaning that as soon as the SNU starts playing, Korsakow goes looking for SNUs with matching IN keywords, to show their assoociated Previews. The Time can be changed by clicking once in the appropriate row in the OUT Keywords, and then moving the scrubber to another point in the media asset’s timeline. The Time can also be manually edited by double-clicking and typing in the textbox.
  • Korsakow automatically re-organizes the rows of OUT Keywords according to their associated Time setting, ie chronologically. Assuming they share the same Time setting, OUT Keywords can also be typed on one line, separated by a comma or a single space.
  • Use the SNU Editor in conjunction with the All Keywords Tool (see Tool > All Keywords) to speed up the SNUifying process considerably.

Max Links

Optional. Advanced feature. Defines the maximum number of links a search of a keyword-line can trigger. If this value has already been defined in Project Settings, it can be overwritten here for each individual keyword-line.

Preview

Select the media asset that will be used as the SNU’s Preview using the pulldown menu. A small Preview pane helps identify the correct media asset.

Preview text

Optional. Any text placed here will appear on top of (ie superimposed on) the associated Preview.

Save

Make sure to click on Save after SNUifying!

Cancel

Clicking on Cancel will delete all current changes.


3.0 Interface Editor

Interface Editor

Korsakow Interfaces are the layouts the viewer sees when a Korsakow film plays in the web browser. These chiefly comprise SNU and Preview widgets. It is not necessary to use the Interface Editor to create a Korsakow film. Instead, the Default Interface (three small Preview widgets evenly spaced under one large SNU widget) can be used. However, more advanced Korsakow filmmakers will likely want to use the Interface Editor to add visual variety, or to make the appearance of their Korsakow films an integral part of their storytelling. A Korsakow film can have as many interfaces as there are SNUs. These are designed in the Interface Editor and then assigned while SNUifying: simply select the appropriate interface using the pulldown menu in the SNU Editor. Remember that interfaces can be shared with other Korsakow users via File > Import > Shared Interface and File > Export > Shared Interface.

The Interface Editor can be accessed in two ways: either double-click on an existing Interface in the Korsakow application main window (this is good for editing an existing interface); or, click on the ‘New Interface’ icon in the bottom righthand corner of the Korsakow application main window.

The Interface Editor consists of a stage with an adjustable grid, and a righthand column with two tabs: Tools and Settings. The stage simulates a browser window. Items that appear on the stage are called Widgets. These can be dragged onto the stage from the Widgets palette in the Tools tab. (Note that the background grid is only for guidance and will not appear in the Exported film.)

  • Unwanted Widgets can be highlighted with a single click and then deleted using the Delete key on the keyboard, or the red Delete button in the Tools tab.
  • Widgets can be moved around by clicking and dragging anywhere inside them. These will snap to the grid. Snapping can be temporarily suspended by holding the ‘ALT’ key (Windows) or Option key (Mac) while dragging.
  • Widgets can be resized by clicking and dragging their corners. These will snap to the grid. Snapping can be temporarily suspended by holding the ‘ALT’ key (Windows) or Option key (Mac) while resizing.
  • By default, resizing enforces the aspect ratio the widget had before you started resizing. This can also be suspended while resizing by holding the SHIFT key (Mac and Windows).
  • All the widgets on the stage can be selected together by using CTRL+A (Windows) or Command+A (Mac).
  • Widgets can be made to overlap one another, either partially or completely. The order of the layers can be controlled using the Arrange options in the Tools tab.

Tools Tab

Info

Shows the size and position of any widget on the stage, after it has been selected (ie clicked once). All measurements are in pixels. These values can also be changed by typing directly into the boxes. The position of a widget, in x and y values, is measured from the top lefthand corner of the widget.

Properties

Shows the adjustable features for any widget selected on the stage, in addition to its size and position. The available features depend on the kind of widget. For example, the Properties associated with the Preview and Subtitles widgets include font information such as colour, weight, and size.

Arrange

Widgets can overlap or be placed on top of one another. This feature provides four options for adjusting the layering of widgets within the interface: move to back; move backwards; move forwards; move to front.

Widgets

A list of available widgets. To use a widget in an interface design, click on its name and drag it to the stage. Currently available widgets are as follows:

Basic Widgets
    • SNU: The main window where SNUs play. At least one is required.
    • Preview: There is no limit to the number of Previews.
    • Insert Text: Required if any Insert Text has been created during SNUifying.
    • Subtitles: Required if Subtitles have been created.
Media Controls
    • Playhead: Optional. Places a simple icon on the stage which moves left to right in sync with the current SNU. Usually placed directly under the SNU widget and adjusted to match its width. Design options include size and colour.
    • Play Button: Optional. Places a simple icon on the stage which will allow the viewer to pause and play a SNU.
    • Master Volume: Optional. Adds a volume control to the Korsakow Film.
    • Play Time: Optional. Displays time elapsed for current SNU.
    • Total Time: Optional. Displays total run time for current SNU.
    • Fullscreen Button: Optional. Places a simple icon which will allow the viewer to enter and exit fullscreen view.
Experimental Widgets (currently unsupported)
  • Comments: Optional. Only works with WordPress plugin installed.
  • History: Optional. Shows a graphic bar to indicate the path taken by the viewer when playing the film.
  • Preview (Multi Link). Preview window where the available SNUs are specified in a scrollable list.

Settings Tab

Interface

Name: The name of the interface as it appears in the Korsakow application main window.

Grid

Controls the size of the grid on the stage. Widgets will snap to this grid unless overrides are used (see above). Measured in pixels. Alternatively, an aspect ratio can be selected to match the grid to the aspect ratio of the media assets.

Media

Click Sound: Optional. Selects the sound file to be played when the viewer clicks on something in the film. (The sound file must be dragged and dropped into the Korsakow application main window before it will show up here.) Its volume can also be set here using the slider.

Default Background Image: Optional. Applies a background image to the selected interface. Alternatively, a solid background colour can be selected and applied by clicking on the colour button and choosing an appropriate colour.

Preview

Show Background: Controls whether or not the background image is displayed in the Interface Editor.


4.0 Adding Subtitles

Subtitles can be added to specific SNUs in a k-film, but please note that this feature needs significant improvement. Begin by preparing your subtitles (one text file per SNU) as follows: Create a new plaintext (.txt) file, in any basic text editor (eg TextEdit). Input your subtitle info as indicated, below, making very careful note of the colons, commas, linebreaks, etc:

1.
00:00:20,000 --> 00:00:24,400
In connection with a dramatic increase in crime in certain neighbourhoods,

2.
00:00:24,600 --> 00:00:27,800
the government is implementing a new policy.

etc.

Save your work as a plain text file (.txt) in Unicode (UTF-8) format. The subtitles will not work properly if the plaintext file is not saved in UTF-8. Now duplicate this file, and manually change the new file’s extension from .txt to .srt. For example, mysubtitles.txt becomes mysubtitles.srt. Do not drag the .srt file into your project in the main Korsakow window. (More information on the SRT file format.)

Now open the Interface editor and drag the Subtitles widget to the stage. The conventional place for this is directly under the Main Media widget. Change its size (eg to match the width of the Main Media widget) via the Info panel in the Tools bar or by dragging the corners or edges of the widget (hold the Shift key down to adjust height or width separately). The Subtitles widget can be placed over other widgets, if desired. If you have more than one Interface in your project, make sure it’s the right one, ie the interface associated with the SNU that requires subtitling.) Save the modified interface.

In the main Korsakow window, right-click (PC) or control-click (Mac) on the SNU, and choose Get Info. Select the subtitle file from your harddrive and save your work. Your subtitles should now appear under this SNU when it plays in the k-film.

Troubleshooting: The .srt format is absolutely unforgiving, so if your subtitles do not show up, go through each .srt file very carefully, finding and deleting any extra lines or spaces, making sure the timing of one subtitle doesn’t overlap the timing of the next one (and the one before it), and so on. The numbers must be sequential, and include a period. Notation for timing is critical too. This is correct: 00:00:24,600 but these are not: 00:00;24,600 (should be colon, colon, comma) and 00:0:24,600 (should be 2 figures, 2 figures, 2 figures, three figures) and 00:00:24:600 (again, should be colon, colon, comma).


5.0 Viewing a Korsakow Film

The viewing of a k-film is designed to be as intuitive as possible. We prefer minimal intrusions into the narrative flow, so Korsakow films offer a very simple interface to the viewer, with clickable previews. Controls such as buttons and sliders often interfere with viewing rather than enhancing it.

The viewer can control the narrative using the spacebar to pause the k-film, the forward-arrow key to advance the k-film to the end of the current SNU, and the browser’s backward and forward buttons to review or advance the k-film as it plays.

Several widgets are available in the Interface Editor to allow the viewer more visible control over the viewing of a k-film, such as a Playhead, fullscreen toggle (in Media Controls), and volume control. We suggest using these sparingly to avoid unnecessary clutter.

Viewers can also link directly to a specific SNU in an online k-film, or embed the SNU in their own website. Moving the mouse over the current SNU in an online k-film reveals a button called “Share”. Clicking on the Share button pauses the k-film and reveals three options: a line of HTML code that can be copied to link to the k-film; a line of html code to be copied to link to that specific SNU; and, some html and javscript code that can be copied and pasted into another website to visibly embed that SNU. We think this feature might be particularly useful when, for example, writing an online review of a k-film. Note that the Share function only works and is only visible when the k-film has been published online.