Keymap

From Official Kodi Wiki
Jump to navigation Jump to search

Template:Keyboard navigation

Cleanup.png This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.


Keyboard.xml is a XML base keymap file that define the mappings of keys (keyboard keys, mouse/remote/joysticks buttons and more) to XBMC actions. Keyboard.xml was first introduced in XBMC 10 ("Dharma"), in versions prior to that it was called Keymap.xml.

Location of keymaps

Keymap configuration files are stored in the "keymaps" folder in the userdata folder:


The keymap configuration files that ship with XBMC are stored in the "/system/keymaps/" folder within the XBMC root directory.

All *.xml files in these folders are applied as keymaps. All *.xml files are processed in alphabetical order. Keymaps defined in an .xml file add to or override mappings in previous .xml file. Keymaps defined in user folders add to or override mappings in the global keymap.

By default there will be no files in these locations, so grab one from the link below to make a new one/over-ride:

Default keymaps shipped with XBMC

101 on keymaps

For a full guide, see: HOW-TO:Modify keyboard.xml

Now, you don't actually need to copy the default keymap, because XBMC is smart enough to only load changes, so you can just add one or two keys and it will apply it to the existing keymap. It's nice to use a full copy because it makes it easier to see what is and isn't in use, and when you see the full mapping you get a feel for what the different options do, etc.

Structure

There is one global keymap and several window-specific keymaps.
XBMC falls back to the global map when the window-specific map hasn't bound the key being pressed.

The format of keymapping files is as follows:

<keymap>
  <global>
    <gamepad>
      <A>Select</A>
      [...]
    </gamepad>

    <remote>
      <select>Select</select>
      [...]
    </remote>

    <keyboard>
      <enter>Select</enter>
      [...]
    </keyboard>

    <universalremote>
      <obc25>XBMC.ActivateWindow(MyMusic)</obc25>
      [...]
    </universalremote>

    <joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
      <button id="15">Select</button>
      [...]
    </joystick>
  </global>

  <Home>
    [...]
  </Home>

  [...]

</keymap>

As you can see, it's divided into a <global> section, and a number of window sections (such as <Home>).
A list of the available window names can be seen here. The WINDOW can also be a custom window formatted as <windowId#> (e. g. <window1113>).
Each of these sections can contain Gamepad, Remote, Keyboard, Universal Remote, and custom Joystick sections.

The format for mapping a particular key under one of these device types is as follows:

  <keyname>action</keyname>

Keynames

Gamepad Section

An up to date list of the available actions can be found in the source code of XBMC in ButtonTranslator.cpp where the TranslateGamepadString() function does the work.

Example:

<gamepad>
  <A>Select</A>
</gamepad>

Remote Section

An up to date list of the available actions can be found in the source code of XBMC in ButtonTranslator.cpp where the TranslateRemoteString() function does the work.

Example:

<remote> 
  <play>Play</play>
</remote>

Universal Remote Section

To map Universal Remote buttons using the RCA infrared protocol, you may add <universalremote> sections to keymap.xml.
In this case, the tags used are <obc#> where # is the original button code (OBC) of the button.
You would put it inside a <universalremote> section in the <window> or <global> sections.

Example:

<universalremote> 
  <obc148>Stop</obc148>
</universalremote>
Will map Stop Playback to the RCA DVD repeat button <obc148>, which is not used by XBMC by default.
  • Note: ensure that the <universalremote> section is NOT added 'within' the <remote> section - it can appear before or after. Otherwise it will not be recognised and produces errors in the logfile.

Remote keys can be observed in the xbmc.log file (~/.xbmc/temp/xbmc.log on Linux) when debugging is enabled in the GUI (Settings -> debugging ). The list of pre-defined OBC codes can be found at XBIRRemote.h.

Keyboard Section

Valid keyboard keymap syntax includes <keyname>, <key id="">, and <keyname mod="">.

Mapping for arbitrary key codes can be configured using the following syntax:

<key id="123">

where "123" is replaced by the key code.

A full list of valid keynames can be found in

Example:

<keyboard>
  <key id="123">action</key> -- id is the keys keycode. >
  <a mod="shift,alt">action</a> -- corresponds to shift-alt-a, the mod="" syntax is enabled since build 26407. >
  <space>action</space> -- for a complete list of valid keynames, see ButtonTranslator.cpp or List of XBMC keynames above. >
</keyboard>

Microsoft XBOX 360 Controller Section

Valid Microsoft XBOX 360 Controller syntax is <button id="x">action</button> or <axis id="x" limit="y">action</axis>.

Here is a full list of button and axis mappings:

Buttons:

  • 1 - A
  • 2 - B
  • 3 - X
  • 4 - Y
  • 5 - LB
  • 6 - RB
  • 7 - Start
  • 8 - Guide
  • 9 - Left Stick Button
  • 10 - Right Stick Button
  • 11 - D-Pad Up
  • 12 - D-Pad Down
  • 13 - D-Pad Left
  • 14 - D-Pad Right
  • 15 - Back

Axis Mappings:

  • 1 - Left Stick L/R
  • 2 - Left Stick U/D
  • 3 - Left Trigger
  • 4 - Right Stick L/R
  • 5 - Right Stick U/D
  • 6 - Right Trigger

Example:

<keymap>
  <global>
    <joystick name="Xbox 360 Wireless Receiver">
      <altname>Controller (Gamepad for Xbox 360)</altname>
      <altname>Controller (XBOX 360 For Windows)</altname>
      <button id="1">Select</button>
      <button id="2">Back</button>
      <button id="3">FullScreen</button>
      <button id="4">ContextMenu</button>
    </joystick>
  </global>
</keymap>

Sony PlayStation 3 Sixaxis Controller Section

Valid Sony PS3 Sixaxis Controller syntax is <button id="x">action</button> or <axis id="x" limit="y">action</axis>.

Here is a full list of button:

Buttons:

  • 1 - Select
  • 2 - L3
  • 3 - R3
  • 4 - Start
  • 5 - D-Pad Up
  • 6 - D-Pad Right
  • 7 - D-Pad Down
  • 8 - D-Pad Left
  • 9 - L2
  • 10 - R2
  • 11 - L1
  • 12 - R1
  • 13 - Triangle
  • 14 - Circle
  • 15 - X
  • 16 - Square

Example:

<keymap>
  <global>
    <joystick name="PLAYSTATION(R)3 Controller (00:06:F7:66:24:76)">
      <button id="1">Info</button>          <!-- Select -->
      <button id="2">ContextMenu</button>   <!-- L3 -->
      <button id="3">CodecInfo</button>     <!-- R3 -->
      <button id="4">Play</button>          <!-- Start -->
      <button id="5">Up</button>            <!-- D-Pad Up -->
      <button id="6">Right</button>         <!-- D-Pad Right -->
      <button id="7">Down</button>          <!-- D-Pad Down -->
      <button id="8">Left</button>          <!-- D-Pad Left -->
      <button id="9">Rewind</button>        <!-- L2 -->
      <button id="10">FastForward</button>  <!-- R2 -->
      <button id="11">SkipPrevious</button> <!-- L1 -->
      <button id="12">SkipNext</button>     <!-- R1 -->
      <button id="13">ParentDir</button>    <!-- Triangle -->
      <button id="14">Stop</button>         <!-- Circle -->
      <button id="15">Select</button>       <!-- X -->
      <button id="16">OSD</button>          <!-- Square -->
    </joystick> 
  </global>
</keymap>

Custom Joystick Configuration

Custom joysticks are defined using the following syntax:

<joystick name="JOYSTICK NAME">
  <button id="BUTTON ID">action</button>
</joystick>

Getting the joystick name:

  • On linux: 'cat /proc/bus/input/devices'
  • or see your xbmc log file

Getting the button ids:

  • 'id' is the button ID used by SDL. Joystick button ids of connected joysticks appear in xbmc.log when they are pressed. Use your log to map custom buttons to actions.

Example:

<joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
  <button id="15">Select</button>
  <button id="14">PreviousMenu</button>
</joystick>

Actions

The most recent available actions can be found in the TranslateActionString() method in in ButtonTranslator.cpp.

For those debugging integer action codes from the debug log, the mapping of action codes to constants is in Key.h

In addition to the following actions, you can also use Built-in scripting in XBMC.

Main actions
Action Description
Left Move left off a control.
Right Move right off a control.
Up Move up off a control.
Down Move down off a control.
Select Select a button, or an item from a list of thumb view.
Enter ? (ACTION_ENTER) Not sure about all areas, but on some windows this will be the same as the "done" on screen button.
PageUp Scroll up on page in a list, thumb, or text view.
PageDown Scroll down on page in a list, thumb, or text view.
Highlight Highlight an item in a list or thumb view.
ParentDir Go up a folder to the parent folder.
PreviousMenu Go back to the previous menu screen.
Back Go back in navigation.
Info Show the information about the currently highlighted item, or currently playing item.
Pause Pause the currently playing item.
Stop Stop the currently playing item.
SkipNext Skip to next video in playlist. If no playlist, then skip to next chapter in video.
SkipPrevious Skip to previous video in playlist. If no playlist, then skip to previous chapter in video.
FullScreen Toggles full-screen content playback (either visualisation or video playback)
togglefullscreen Changes whether the app is displayed full-screen or windowed (on windowing OSs)
AspectRatio Toggle through the various aspect ratio modes (Normal is the preferred option).
StepForward Step forward 30 seconds in a video.
StepBack Step back 30 seconds in a video.
BigStepForward Step forward 10 minutes in video.
BigStepBack Step back 10 minutes in video.
SmallStepBack Step back 7 seconds in the current video.
Seek(##) A definable seek action, where ## is a number of seconds. For example, to make a seek action that goes forward 25 seconds use Seek(25), and to make a seek action that goes back 36 seconds use Seek(-36). (v15 Isengard addition)
ChapterOrBigStepForward Go to to next chapter in video. If no chapters, then step forward 10 minutes in video. (v13 Gotham addition)
ChapterOrBigStepBack Go to previous chapter in video, If no chapters, then step back 10 minutes in video. (v13 Gotham addition)
NextScene Go to next scene that is marked in an Edit_decision_list file.
PreviousScene Go to previous scene that is marked in an Edit_decision_list file.
OSD Toggles the OSD (On Screen Display) while playing an item.
PlayDVD Start playing a DVD (goes to the DVD menu)
ShowVideoMenu Go to the DVD Video menu when playing a DVD.
ShowSubtitles Toggles whether subtitles are shown or not.
NextSubtitle Change to the next subtitle language, if there is more than one.
SubtitleShiftUp Move subtitles up
SubtitleShiftDown Move subtitles down
SubtitleAlign Subtitle position control
CodecInfo Show codec information about the currently playing item (during video or visualisation playback)
NextPicture Move to the next picture in a slideshow.
PreviousPicture Move to the previous picture in a slideshow.
ZoomOut Used in picture, slideshow or video fullscreen to zoom out of the current image/video.
ZoomIn Used in picture, slideshow or video fullscreen to zoom in to the current image/video.
IncreasePAR Used in video fullscreen to increase the pixel aspect ratio (stretch).
DecreasePAR Used in video fullscreen to decrease the pixel aspect ratio (stretch).
Queue Queue the item to the current playlist
PlayNext Queue the item to the next position in the current playlist
Filter Opens the mediafilter dialog in the video and musiclibrary. Used in the advanced filter for the video library.
Playlist Toggle to playlist view from My Music or My Videos
ZoomNormal Normal (fullscreen) viewing in My Pictures
ZoomLevel1 Zoom to 120% in My Pictures
ZoomLevel2 Zoom to 150% in My Pictures
ZoomLevel3 Zoom to 200% in My Pictures
ZoomLevel4 Zoom to 280% in My Pictures
ZoomLevel5 Zoom to 400% in My Pictures
ZoomLevel6 Zoom to 600% in My Pictures
ZoomLevel7 Zoom to 900% in My Pictures
ZoomLevel8 Zoom to 1350% in My Pictures
ZoomLevel9 Zoom to 2000% in My Pictures
NextCalibration Used in Video + GUI calibration
ResetCalibration Used in Video + GUI calibration
AnalogMove Move in the calibration screens, and while zoomed in My Pictures.
Rotate Rotate a picture in My Pictures
rotateccw ? (ACTION_ROTATE_PICTURE_CCW)
Close Used to close a dialog
subtitledelay ? (ACTION_SUBTITLE_DELAY)
SubtitleDelayMinus Decrease the delay amount of subtitles (use if subtitles are displaying too late)
SubtitleDelayPlus Increase the delay amount of subtitles (use if subtitles are displaying too early)
audiodelay ? (ACTION_AUDIO_DELAY)
AudioDelayMinus Decrease the delay amount of audio (use if audio is being heard too early)
AudioDelayPlus Increase the delay amount of audio (use if audio is being heard too late)
AudioNextLanguage Change to the next audio track in a video with multiple audio tracks.
NextResolution Used in Video calibration
Number<0-9> Used to input the number 0 through 9
FastForward Toggle the fastforward speed between normal play, 2x, 4x, 8x, 16x, and 32x.
Rewind Toggle the rewind speed between normal play, 2x, 4x, 8x, 16x, and 32x.
Play Play the selected item (or folder of items).
PlayPause Play the selected item (or folder of items). Will also pause media when something is already playing.
Delete Used in My Files to delete a file.
Copy Used in My Files to copy a file.
Move Used in My Files to move a file.
Rename Used in My Files to rename a file.
HideSubmenu <depreciated>
Screenshot Take a screenshot of the current screen.
Reboot Reboot
ShutDown() Shutdown and power off
VolumeUp Increase the volume of playback.
VolumeDown Decrease the volume of playback.
Mute Mute the volume.
volampup ? (ACTION_VOLAMP_UP)
volampdown ? (ACTION_VOLAMP_DOWN)
audiotoggledigital ? (ACTION_TOGGLE_DIGITAL_ANALOG)
BackSpace Used in the virtual keyboards to delete one letter.
ScrollUp Variable speed scroll up for analog keys (stick or triggers)
ScrollDown Variable speed scroll down for analog keys (stick or triggers)
AnalogFastForward Variable speed fast forward for analog keys (stick or triggers)
AnalogRewind Variable speed rewind for analog keys (stick or triggers)
AnalogSeekForward Variable speed seeking for analog keys (stick or triggers)
AnalogSeekBack Variable speed seeking for analog keys (stick or triggers)
MoveItemUp Used to rearrange playlists
MoveItemDown Used to rearrange playlists
Menu Focus the menu control (e.g. sidebar in confluence) which is specified by the skin in different windows (e.g. Movies, Music, PVR etc.) (v16 Jarvis addition)
ContextMenu Pops up a contextual menu
Shift Used in Virtual Keyboard to switch to upper or lower case letters
Symbols Used in Virtual Keyboard to switch to or from symbols mode
CursorLeft Used in Virtual Keyboard to move the current cursor point to the left
CursorRight Used in Virtual Keyboard to move the current cursor point to the right
ShowTime Used to show the current play time in music + video playback
visualisationpresetlist Shows the visualisation preset list
ShowPreset Shows the current visualisation preset (milkdrop/spectrum)
NextPreset Next visualisation preset
PreviousPreset Previous visualisation preset
LockPreset Lock the current visualisation preset
RandomPreset Switch to a new random preset
IncreaseRating Used to increase track rating in full screen playback (press info on track and use pageplus on keyboard/remote
DecreaseRating Used to decrease track rating in full screen playback (press info on track and use pageminus on keyboard/remote
ToggleWatched Toggles watched/unwatched status for Videos
NextLetter Move to the next letter in a list or thumb panel. Note that SHIFT-B on the keyboard will take you to the B's.
PrevLetter Move to the previous letter in a list or thumb panel. Note that SHIFT-Z on the keyboard will take you to the Z's.
JumpSMS<2-9> Jump through a list using SMS-style input (eg press 2 twice to jump to the B's.)
FilterSMS<2-9> Filter a list in music or videos using SMS-style input.
verticalshiftup ? (ACTION_VSHIFT_UP)
verticalshiftdown ? (ACTION_VSHIFT_DOWN)
scanitem ? (ACTION_SCAN_ITEM)
reloadkeymaps Reload keymap, loading any changes made to the keymap since started up.
increasevisrating ? (ACTION_VIS_RATE_PRESET_PLUS)
decreasevisrating ? (ACTION_VIS_RATE_PRESET_MINUS)
firstpage ? (ACTION_FIRST_PAGE)
lastpage ? (ACTION_LAST_PAGE)
guiprofile ? (ACTION_GUIPROFILE_BEGIN)
red ? (ACTION_TELETEXT_RED)
green ? (ACTION_TELETEXT_GREEN)
yellow ? (ACTION_TELETEXT_YELLOW)
blue ? (ACTION_TELETEXT_BLUE)
CreateBookmark Creates a bookmark of the currently playing Video (v13 Gotham addition)
CreatEpisodeBookmark Creates an episode bookmark of the currently playing multi-episode file (e.g. S01E01E02). An episode bookmark specifies the end of the one and the begin of the other episode (v13 Gotham addition)
NextChannelGroup PVR Goes to the next channel group when using live TV. Works only within PVR windows + channel osd. (v13 Gotham addition)
PreviousChannelGroup PVR Goes to the previous channel group when using live TV. Works only within PVR windows + channel osd. (v13 Gotham addition)
ChannelUp PVR Used to switch up to the next channel. Works only if you playback TV or radio (v13 Gotham addition)
ChannelDown PVR Used to switch down to the previous channel. Works only if you playback TV or radio(v13 Gotham addition)
PlayPvr PVR Starts playback a TV or radio channel depends on the last played channel. (v13 Gotham addition)
PlayPvrTV PVR Starts playback a TV channel. Will playback the last played channel if available. (v13 Gotham addition)
PlayPvrRadio PVR Starts playback a radio channel. Will playback the last played channel if available. (v13 Gotham addition)
Record PVR record current playing channel or selected item in windows like EPG (v13 Gotham addition)
StereoMode Toggle 3D/Stereoscopic mode (v13 Gotham addition)
ToggleStereoMode Toggle 3D/Stereoscopic mode (v13 Gotham addition)
SwitchPlayer Select player to use, such as internal (DVDPlayer/PAPlayer), UPnP "play using" targets, external players. (v13 Gotham addition)
UpdateLibrary(video) Update Movie/TV-Show library (only tested with v13 Gotham addition).
SetRating For use when playing music. Will pop-up a 1-10 userrating select dialog, to rate the currently playing song. (v17 Krypton addition)
Other
Action Description
noop No action. Used to specifically disable a key.


Windows


Additional keys

Other keys that can be mapped to actions.

Media keyboards/remotes

  • browser_back
  • browser_forward
  • browser_refresh
  • browser_stop
  • browser_search
  • browser_favorites
  • browser_home
  • volume_mute
  • volume_down
  • volume_up
  • next_track
  • prev_track
  • stop
  • play_pause
  • launch_mail
  • launch_media_select
  • launch_app1
  • launch_app2
  • play
  • pause
  • fastforward
  • rewind
  • channelup
  • channeldown

Mouse actions

  • leftclick
  • rightclick
  • middleclick
  • doubleclick
  • wheelup
  • wheeldown
  • mousedrag
  • mousemove

See also

Development: