Python

NOTE: Python does not yet work in 64bit!

If you're looking for the open-sourced C++ Embedding Code.

How to Use

1. On Mac: it's built in. On Windows: requires Python 2.7, 32bit. You can download it here.
2. Run kJams 2. Go to the Advanced menu and see the Python submenu
3. in your user's Music/kJams folder there is now a Python folder. Put your scripts in there to see them in the Python menu (re-start kJams)

Note if you find it stops working on mac, got to Terminal and issue this:

tccutil reset AppleEvents

This will reset the "are you sure this is okay" security prompt, and the OS should ask if it's okay that kJams control iTunes, be sure to say OK and not deny the request

Tips

• Pick "Advanced->Python->Reveal “kjams.py”", this will give you a list of enums for commands, server, and reveal other commands you can call
• A script named "startup.py" will, if present, be run on startup, so if eg: you always want to ensure some prefs are set correctly, regardless of what someone may have changed, you can use this script to set some prefs the way you like them.
• Picking anything from the Python menu will run it. Holding the alt/option key when picking it will reveal (open) the file instead
• You should open each of the files and look at them for examples
• you can edit your scripts live and re-run them, no need to quit and re-run kJams
• if you create new scripts or remove old ones, or rename one, you must restart kJams to see them in the menu
• always edit your scripts as UTF8, and be sure to include the header "# -*- coding: utf-8 -*- " as the first line. that way, you can just enter any unicode characters you wish as string literals. no need to prefix with u, tho that is optional and will work.
• when passing parameters, tuples and lists are considered the same thing to kJams (an array), and are interchangeable.

What's working

• All the Scripting commands
• Access to every menu item (including sub menus)
• Access to all preferences including secret prefs (prefs that otherwise have no user interface)
• ability to show a progress bar in the activity window
• ability to kill off a script (stop sign in activity window)
• song meta data editing
• get/set selected playlist
• get/set selection within playlist
• message dialog, with title and message, up to 3 buttons, and 1 check box
• interactive string dialog, title, message, default string, OK, Cancel
• set keyboard shortcuts
• add song to any playlist
• reorder songs within a playlist (including singer)
• new playlist
• ability to show ShowScreens
• ability so script iTunes (get play state, get/set volume)
• Much of the Server functionality including:
  • fetching playlists (eg: Library, Rotation, Venue (list of singers)) etc
  • fetching info including venue name
  • singer creation and/or login
  • getting singers' lists (tonight, history, faves)
  • add songs to singer
• crossfade with iTunes

What's Coming

• remove song from playlist
• whatever else you need

Ideas

• auto cross fade with your favorite DJ app
• Twitter feed - Current singer and song
• a Rate the singer app for iPhone or 'Droid
• update web site with current stats
• load some videos playing behind the kJams window (with transparency), with VLC or QuickTime Player
• fix prefs on startup
• make your own iOS or Droid app that interacts with kJams

How to modify an existing script

The TL;DR is: make a copy of the existing script and modify that

1. Hold the option/alt key and pick the script to reveal it
2. Mac:
   1. revealing will open your script in a text editor
3. Windows:
   1. revealing will show the script file in Windows Explorer
   2. open that file in a text editor
4. in the File menu of your text editor, pick "Save As..."
5. go to your Python folder here: /Users/<you>/Music/kJams/Python/
6. Re-name the file so you can distinguish it from the built-in one (eg: prepend "My " to it's name)
7. save it in that location with the new name