How to Modify the Default Key Settings

Detailed information on how to modify your local .shuttlerc file is described next, but if you need help you can request more information in the forum at https://cinelerra-gg.org. In the shuttlerc file, a # always represents a comment and blank lines are ignored. The first thing you must do is copy the system supplied shuttlerc file to your $HOME directory and rename it as .shuttlerc (with a period).

The shuttlerc file has sections that in the case of CINELERRA-GG, represent different windows allowing you to set the keys, K1-K15 for the Pro and K5-K9 for the Xpress, the shuttle wheel positions of S0/S1/S-1 for stop, S2 through S7 for wheeling to the right, and S-7 through S-2 for wheeling to the left for reverse. Then there is JR to jog right (clockwise) and JL to jog left (counter-clockwise) for the inner smaller wheel for single frame movement. See the key arrangement on a later page for location of the keys for each of the two different shuttles.

The sections are surrounded by brackets for windows such as CINELERRA-GG (the main window), Viewer, Composer, Resources, Load, and Default. If you want the keys to be defined the same in every window, you can bracket each window on lines one right after the other and then just define one set of keys. The other lines will have the key name/shuttle position followed by its assigned value. The values you use for the keys are usually shortcuts and have to be operationally defined within CINELERRA-GG. For example, the shortcut “f” to go fullscreen is defined so can be used; however the shortcut “h” is not defined so will not do anything. You can check the file, shortcuts.html, for some options to use.

Next are a few actual examples from the default cindat_path/shuttlerc file.

The next brackets represent sections. Default, Resources, Load windows all use the same key values.

[Default]
[Resources]
[Load]
K5 XK_Home
K6 XK_Button_1 # same as mouse button 1
K7 XK_Button_2 # same operation as mouse button 2
K8 XK_Button_3
K9 XK_End
# for example, in the Load menu, use scroll up to get to the next file name
JL XK_Scroll_Up
JR XK_Scroll_Down

Cinelerra with brackets around it next, is the section with some key definitions for the main window.

[Cinelerra]

# Most useful functions have to be on K5-K9
# because Xpress only has 5 keys
K5 XK_Home      # Beginning
K6 XK_KP_6      # Reverse, or if playing Stop
K7 XK_KP_0      # Stop
K8 XK_KP_3      # Play, or if playing Stop
K9 XK_End       # End
...
S-7 REV_16     	# Next 6 are reverse keys
S-6 REV_8      	#  the number on the end represents speed
S-5 REV_4      	#  number can be decimal up to 64
S-4 REV_2      	#  2 means 2x or double speed
S-3 REV_1
S-2 REV_0.5    	#  0.5 represents 1/2 speed
S-1 XK_KP_0    	# Because the Shuttle does not generate S0,
		#   have to use S-1
S0  XK_KP_0   	# Hardware does not generate S0
S1  XK_KP_0   	# Because the Shuttle does not generate S0,
		#   have to use S1
S2  FWD_0.5
S3  FWD_1
...

An explanation for the above REV and FWD key symbol values is necessary to facilitate user preferences. Obviously REV stands for reverse and FWD for forward. You can set any speed up to and including 64x (that is, 64 times the normal speed) on any of the S keys. First in the line is the key name such as S-3 and then the key direction of FWD or REV followed by the symbol for underscore (_) and then the numerical value to use. For example, if you want the 5^th forward position, S5, to play 10 ${\frac{{1}}{{2}}}$ times faster, you would use the statement S5 FWD_10.5. Integer or decimal numbers are legal.

For the Viewer, you may want keys defined to do a Splice or an Overwrite so define differently. Note that assignments that contain single character letters must be enclosed in quotes.

[Viewer]
# Splice - Viewer only; may be defined
# differently than Composer or Cinelerra
K2 "v"
K4 "b"		# Overwrite

To change any key value to an alternative value, just edit the file and make the changes. Besides just keys and alphabetic letters of numbers, you can also use any CINELERRA-GG value that contains the combination with Shift, Alt, and Ctrl. For keys that are not printable characters, you can look up the symbol name to use for a specific operation in the file called: /usr/include/X11/keysymdef.h. Some examples:

K10 Alt-XK_Left	  # Go to previous edit \\
K13 Ctrl-XK_Right # Go to next label

For sequences of one or more printable characters, you can just enclose them in double quotes. For example in the [Composer] section, to go into or out of fullscreen mode, automatically start playing and put a label there, you could define a key like this: K7 “f l” - that is printable character f, a space, and printable character l.

After modifying .shuttlerc, the next time you use the shuttle, your changes will automatically take affect without even having to stop and restart Cin. However, the first thing to try if problems is to stop CINELERRA-GG, unplug the shuttle, wait a few seconds, plug it in again, and then restart cin. If for some reason, the shuttle keys still do not work after that, you may have an incorrect setup and you will have to correct that first. For example, if you define S5 twice within the CINELERRA-GG setup, it will fail. It is suggested that if you make changes, you should initially uncomment DEBUG in the .shuttlerc file and start up CINELERRA-GG from a terminal window so that you can make sure it is working and has no output errors. An error might look like:

dupl key name: [Cinelerra]K1
shuttle config err file: /root/.shuttlerc, line:37

Keep in mind when changing the values, that the ShuttleXpress has fewer buttons so if you define K1 it will only work for the ShuttlePro.

Any time you are having trouble with your shuttle, you can copy the default shuttlerc file from cindat_path/shuttlerc to your local .shuttlerc file, and edit that to switch to DEBUG mode by removing the # comment from the DEBUG line. But you will have to have started Cin from a terminal window to see the key values. The first time you use the shuttle or after you change the file, the current assignments will show in the terminal window so will look something like:

[Cinelerra] # 1
K5[D]: XK_KP_0/U
K5[U]: XK_KP_0/U

When you are in DEBUG mode and are just working away, what you will see is something like this:

key: 0058 1
key: 0055 0

or:

shuttle:  00 00 00 00 00
key: XK_Home 0

When you change the focus from one window to another, you will see something like this:

new focus: 04c00137
new translation: Viewer
key: 0059 1

You can also set an environment variable to temporarily use an alternative shuttle configuration file for testing as in:

export SHUTTLE_CONFIG_FILE=/tmp/shuttlerc_test

The shuttle wheel occasionally will not stop after you have wheeled it to play forward. This is a documented known problem from the original code so you just have to joggle it a little in the other direction and then it will stop. S0 does not always generate a signal to do a stop and that is why S1 and S-1 have to be used to relay the stop instead. Also, if you have a fullscreen Composer or Viewer up and the regular one also, the fullscreen takes precedence.