We show you how to document your projects, sets and custom devices with Live's Lessons facility.
You've undoubtedly encountered Live Lessons. They appear in the collapsible Help View panel along the right-hand edge of Live's user interface and include release notes for Live updates, information about filing crash reports, and documentation for newly installed third-party content. The panel opens automatically in these cases, but you can also open it manually by choosing Help View from Live's View menu. This reveals links to Live's built-in lessons, as well as to third-party content you've installed in Live's library.
What you may not have discovered is that you can create your own lessons to accompany your sets, or to document your custom creations, such as device racks, group templates and so on. The process is neither documented nor supported by Ableton, but it is well covered in the Live User Forum. If you stick to the basics, it's not difficult to do, and it provides a welcome alternative to attaching text to tracks, clips, and devices in the Info View.
There are actually three kinds of Live Lessons, differentiated by where they reside and how they are accessed. Built‑in lessons are provided by Ableton and stored within the Live application. These comprise most of the lessons that are linked to when you open Help View. Although you can hack your way in and make changes to the built-in lessons, there are no good reasons to do so and many excellent reasons not to.
Add-on lessons usually accompany third-party content such as Max For Live and are automatically installed in the Lessons folder in your Live Library. These are accessed via the last link ('Show all add-on Lessons') under the Lessons tab when you open Help View. You can create your own add-on lessons, but they may get deleted during library upgrades, so backing up is essential. Add-on lessons are a good way to document elements you add to your library, such as custom racks, sets, templates and so on, but in simple cases you may find it easier to simply use Info Text for that.
By far the easiest and most robust option is set-specific lessons. You place those in the project folder and they open automatically when you load the accompanying set. I'll start with these and then talk a little bit about creating add-on lessons at the end.
All you need to create your own lessons is a plain-text text editor such as TextEdit (included in OS X) or Notepad (included in Windows). If you want to include graphics, you'll need a graphics program that can save in the TIF (Tagged Image File) format. Here are the three steps to create a lesson for a set named 'Example 1'.
- Create a new folder within your project folder and name it 'Example 1 Lessons'.
- Create a plain text file in that folder named 'LessonsEN.txt'. (For other languages, replace 'EN' with the appropriate language descriptor (DE, ES, FR, IT or JA.)
- Place all other material for the lesson, such as graphics and linked material (on which, more later), in the Example 1 Lessons folder.
In the simplest case — for example, when you send a set to a collaborator or publish it on your web site — you may want little more than a logo and some text explaining the set. With two exceptions, any text you enter in the text file will appear in the lesson. The exceptions are commands (more on which in a moment) which are preceded with '$', and graphics links, which end with '.tif'. You can display such items as text by enclosing them in quotes. (Note that graphics with the extension '.tiff' don't work, but you can manually change their extensions to '.tif'.)
Formatting that you apply directly to the text (including your choice of font) will not have any effect. However, three basic text-formatting options and a built-in graphic are available:
- Text surrounded by asterisks (*) will appear in bold.
- Text surrounded by forward slashes (/) will appear in bold italic.
- Text preceded by a dash, right arrow, and space (-> ) will be a bullet point, and text indentation will persist until the next Return.
- Divider.TIF is a built-in graphic for a dividing line.
To go beyond a single page of annotation — for example, to keep a log of your sources and different versions of the set — you'll need to learn some basic commands. Commands always begin with a dollar sign ($) and I've shown them in bold for clarity.
For multi-page lessons, you start each page with a Page command ($Page header text). If you want to link to that page from within the lesson, follow the Page command with a TargetName command ($TargetName link name) and then create links back to that page from other lesson pages by using a Link command ($Link your description <GotoPage:link name>). For a summary of other useful commands, check out the 'Hot Links' box.
Add-on lessons differ from set-specific lessons in that you place them in the Lessons folder of your Live Library and you access them from the Lessons section of Live's Help View. This makes them excellent for documenting your own device racks, library clips, custom set templates and so on, because they're accessible from Help View no matter what set you're working on.
The first step in making add-on lessons is to create a new folder in the Lessons folder in Live's library. End the new folder's name with 'Category'. The Help View list of add-on categories is ordered alphabetically by the category folder names, so if you want your category on top, name it accordingly. Create a plain text file named 'CategoryDescriptionEN.txt' inside the new category folder and put a brief description of the category (for example, 'My Tips & Tricks') in the file. This will show up as the category description in Help View.
You can now create add-on lessons in the same way as set‑specific lessons: make a folder with the lesson name followed by 'Lessons', and place lesson materials (plain text file, graphics, linked sets, and so on) in that folder. The add-on lessons table of contents will then display your lessons under the category name(s) you've created. Note that the lesson names will match the names provided in the lessons' first $Page commands rather than the names you've given the lessons folders.
Here is the syntax for some Link commands you'll find useful in creating your own Live Lessons. The brackets in the command lines indicate that you should insert your own information, without the brackets themselves.
Include this Link command in your lesson to reload the lesson (after updating and saving) without having to reload your whole Live set:
$Link Update Lesson <Lesson:Lesson Folder Name>
(Do not include the word 'Lessons' at the end of the lesson-folder name.)
To open a page in your web browser:
$Link (your web site name) <URL>
(Use the full URL, such as 'http://www.swiftkick.com'.)
To load a different Live set from within the same project folder:
$Link (load set X) <Set:set name>
(Include '.als' at the end of the set name.)
To reveal a devices folder in Live's Device browser:
$Link (folder) <BrowseLibraryPresets:path>
(Specify a path within the Presets folder such as 'Audio Effects/Amp'.)
To reveal a Library folder in Live's Hot Swap browser:
$Link (folder) <BrowseLibraryFiles:path>
(Specify a path within the Library folder such as 'Sets/Demo Songs'.)
In any Link command, you can use a .TIF graphic for the description. For example, use this to create a link from your logo graphic to your web site:
$Link (your logo).tif <URL>
For Link commands in set-specific lessons, locating the item you're trying to link to can sometimes become confusing. By default, the path begins at the project level, so, for example, $Link (description) <Lesson:Parent> searches inside the current project folder for the folder named 'Parent Lessons' and then looks for the text file 'LessonsEN.txt' inside that. But suppose you want to create another lessons folder called Child Lessons inside the Parent Lessons folder and link to a LessonsEN.txt file inside that? Using slashes (/) in the path name lets you do that. In the example above, you'd use:
$Link Go to Child <Lessons:Parent Lessons/Child>
But now you're stuck inside the Parent Lessons folder. To move back out to the project folder you'd use two full stops followed by a slash (../), like this:
$Link Go to Parent <Lessons:../Parent>
Notice that for lesson links, full folder names ('Parent Lessons', for example) are used except for the last item ('Child' instead of 'Child Lessons').