PM123 playlist location and navigation strings

PM123 uses a special notation to store playing positions. These strings are used at

• the start and stop positions (slicing) of playlist items or
• the current playing position of bookmarks and
• the navigate command of the PM123 remote interface.

A location string defines an exact point inside a playlist or song. In case of playlists it is an entire call stack. A call stack in general consists of several parts separated by ';' or new-line (if the new-line character is allowed). URLs in the parts may be enclosed with double quotes (") to avoid confusion with special characters.

In case of navigation, the location string may also specify relative positions. This includes that you can also navigate to the parent with "..".

Examples:

my_nested_playlist.lst
my_favorite_song.mp3[2]
3:44

my_nested_playlist.lst;"my_favorite_song.mp3"[2];3:44

The first part navigates to the first occurrence of the file my_nested_playlist.lst in the current playlist.
The second part navigates to the second occurrence of my_favorite_song.mp3 in my_nested_playlist.lst. It is enclosed with quotes. In this case this is optional because the relative URL contains neither a semicolon nor square brackets at the end.
The last part navigates to the offset 3:44 within my_favorite_song.mp3.

my_playlist.lst
 +- my_favorite_song.mp3 (1)
 +- another_song.mp3
 +- my_nested_playlist.lst
     +- my_favorite_song.mp3 (2)
     +- my_playlist.lst (3)
     +- another_song.mp3
     +- my_favorite_song.mp3
        Offset: 3:44
     +- song_#3.mp3
     +- my_favorite_song.mp3
 +- song_#4.mp3
 +- another_nested playlist.lst

1. While this song is part of the location string it is not addressed because the navigation goes into the nested playlist my_nested_playlist.lst first.
2. This item is skipped because the indexer [2] searches for the second location of this song.
3. This recursive entry is skipped anyway.

All the following location strings also navigate to the same location as above.

[3]
[4]
3:44

The above utilizes the index navigation. If you omit the URL in a part all items within the particular playlist count. Note that this includes items that are skipped because they would create a recursion as in note 3. However, it is an error to address this item.

*"my_favorite_song.mp3"[3]
3:44

The flat navigation is identified by the leading asterisk. Flat navigation means that all all non-recursive songs in the nested playlists are taken as one linear playlist. Within this context it is the third instance of my_favorite_song.mp3. Therefore the index [3].

my_nested_playlist.lst[-1]
my_favorite_song[2]
-1:34

*my_favorite_song[-2]
-1:34

Using negative numbers you may do reverse navigation at some parts which may be applied to playlists as well as to songs. It is assumed that my_favorite_song.mp3 has a length of 5:18 in this case. Reverse navigation may be combined with flat navigation as shown in the second example.

*21:06

Flat time navigation can be used to navigate within all songs of a playlist based on the total playing time. Assuming that another_song.mp3 has a length of 3:23 the total time index of our playing location is 21:06.

Playlist location syntax reference

To locate a playlist item use one of the following syntax variants:

• relativeURL or
  absoluteURL
  Navigates to the first occurrence of the above URL within the playlist.
  The path is considered to be relative within the context of the immediately enclosing playlist. The use of '../' is allowed.
• relativeURL[index] or
  absoluteURL[index]
  Navigates to the index^th occurrence of URL within the playlist.
• relativeURL[-index] or
  absoluteURL[-index]
  Navigates to the index^th occurrence of URL within the playlist counting from the back.
• [index] or
  [-index]
  Navigates to item no. index within the playlist. Negative numbers count from the back. It is not recommended to use this method because it easily may miss the mark when the list is modified.
  Note that the numbering differs from the item numbers displayed in the PM123 window, because only the immediate sub items in the playlist count here.
• ?song[index] or
  ?song[-index] or
  ?list[index] or
  ?list[-index]
  Same as [index] but count only songs or playlists respectively.
• *relativeURL or
  *absoluteURL
  Navigates to the first song with the above URL in the current playlist or any of the nested playlists. If the URL is relative it is always resolved within the context of the current playlist also if the nested playlist where it is effectively found resides in a different folder.
• *relativeURL[index] or
  *absoluteURL[index]
  Navigates to the index^th song with the above URL in the current playlist or any of the nested playlists.
• *relativeURL[-index] or
  *absoluteURL[-index]
  Navigates to the index^th song from the back with the above URL in the current playlist or any of the nested playlists.
• *[index] or *[-index]
  Navigates to the index^th song within the current playlist and it's sublists. Negative numbers count from the back.
• *?song[index] or
  *?song[-index] or
  *?list[index] or
  *?list[-index]
  Same as *[index] but count only songs or playlists respectively.
• **...
  Placing two asterisks in front of an URL and/or index specification will also cause flat navigation, but it always counts from the current root. I.e. navigate to the 3^rd song from the current location in a nested playlist that only has 2 songs left, will continue in the root playlist. Note that **?song[1] and **?song[-1] is the function of the previous/next button of PM123.
  While this feature finally breaks with the idea of a call stack it is quite useful for user navigation within nested playlist structures.
• ..
  Navigate one level up. This makes only sense if we are currently not at the top level.
• .
  Navigate before the start of the current level. I.e. if the current item is a playlist the next relative forward navigation will start from the start of the list rather than the current position. If the current item is a song, the time navigation count from the start of the song (or the end in case of negative values).
• /
  Start over from the current root.

It is an error to

• navigate to a non-existing item,
• enclose index with quotes,
• enter a recursive item (see note 3).

If relative navigation is used remember that the current location is usually a song. So you need '..;' to get to the deep most playlist.

Time syntax

• seconds
• seconds.fractional
• minutes:seconds
• minutes:seconds.fractional
• hours:minutes:seconds
• hours:minutes:seconds.fractional
• days:hours:minutes:seconds
• days:hours:minutes:seconds.fractional

It is valid to specify offsets larger the one minute as seconds and so on.
Using a sufficient number of fractional digits it is possible to address locations with an accuracy of one sample. However, some decoder plug-ins may bend it.
You must not enclose time offsets with quotes.