ipodshuffle & teresa Documentation

Note

This documentation is still incomplete and it’s recommended to read the source for the full details.

What is ipodshuffle?

ipodshuffle is a Python Project for iPod Shuffle.

You can use modules to write your own tools:

modules

ipodshuffle

class ipodshuffle.Shuffle(base)
Parameters:base – iPod base path
enable_voiceover

boolean. enable or disable VoiceOver

voice_path_func

callable object or None. when set x.voice, will call it if it’s Not None and enable_voiceover is True

max_volume

integer. 0 do not limit, 3-20 is legal value to limit volume

playlists

list-like object, store all playlists

audiodb

store audio. if you don’t want to copy file to ipod, you can use this

is an instance of ipodshuffle.shuffle.AudioDB

create_track(path_in_ipod=None, checksum=None)
Parameters:
  • path_in_ipod – the path of audio file in the iPod base
  • checksum – CHECKSUM of the audio file in member audiodb
Returns:

a new Track, you may want append it to the playlist.tracks
create_playlist(pl_type=None)
Parameters:pl_type – one in (MASTER, NORMAL, PODCAST, AUDIOBOOK)
Returns:a new PlayList, you may want append it to the playlists
class ipodshuffle.Playlist(shuffle, playlist_type=None, playlistdb=None)
type

MASTER, NORMAL, PODCAST or AUDIOBOOK. Can not change

tracks

list-like, store all tracks of this playlist

voice

tuple. contain text and lang code

class ipodshuffle.Track(shuffle, path_in_ipod=None, trackdb=None)
voice

tuple. contain text and lang code

class ipodshuffle.shuffle.AudioDB(shuffle, log_path, storage_dir)
add(src)

store an audio file to storage dir

Parameters:src – audio file path
Returns:checksum value
get_filename(checksum)
Parameters:checksum – checksum
Returns:filename no storage base part
example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
#!/usr/bin/env python3
import shutil
import os
import tempfile

from ipodshuffle import Shuffle
from ipodshuffle import MASTER, NORMAL, PODCAST, AUDIOBOOK


# for VoiceOver, make sure you have already installed svox TTS softwave
def voice_path_func(text, lang):
    tmp_file = tempfile.NamedTemporaryFile(delete=False)
    tmp_file_name = tmp_file.name + '.wav'
    tmp_file.close()

    cmd = 'pico2wave --wave={} --lang={} {}'.format(tmp_file_name, lang, repr(text))
    # print('\n\n', cmd, '\n')
    os.system(cmd)

    return tmp_file_name


base = '/media/data/ipod_base_doc_text'

ipod = Shuffle(base)

ipod.playlists.clear()

# enable VoiceOver
ipod.enable_voiceover = True

# when track or playlist set "voice = 'text', 'lang code'",  will call this funcition
ipod.voice_path_func = voice_path_func


# create a master playlist, it's the "All songs" in ipod
master_playlist = ipod.playlists.append_one(pl_type=MASTER)


# create a normal playlist
normal_playlist = ipod.playlists.append_one(pl_type=NORMAL)
normal_playlist.voice = 'Bob Dylan', 'en-US'


# copy file to ipod
track1_pathinipod = 'Bob Dylan - Farewell.mp3'
shutil.copyfile('/media/data/music/Bob Dylan/Bob Dylan - Farewell.mp3',
                ipod.base + '/' + track1_pathinipod)
track1 = ipod.create_track(path_in_ipod=track1_pathinipod)
track1.voice = 'Farewell', 'en-US'
normal_playlist.tracks.append(track1)


# use AudioDB copy file to ipod
track2_checksum = ipod.audiodb.add('/media/data/music/Bob Dylan/Bob Dylan - Mr. Tambourine Man.mp3')
track2_pathinipod = ipod.audiodb.get_filename(track2_checksum)
track2 = ipod.create_track(path_in_ipod=track2_pathinipod)
track2.voice = 'Mr. Tambourine Man', 'en-US'
normal_playlist.tracks.append(track2)


# tracks can use same file, and you can set different voices for tracks
track3 = ipod.create_track(path_in_ipod=track1_pathinipod)
track3.voice = 'Farewell, Bob Dylan', 'en-US'
master_playlist.tracks.append(track3)

track4 = ipod.create_track(path_in_ipod=track2_pathinipod)
track4.voice = 'Mr. Tambourine Man, Bob Dylan', 'en-US'
master_playlist.tracks.append(track4)


track5_checksum = ipod.audiodb.add('/media/data/music/Goo Goo Dolls - Name.mp3')
track5_pathinipod = ipod.audiodb.get_filename(track5_checksum)
track5 = ipod.create_track(path_in_ipod=track5_pathinipod)
track5.voice = 'Name, Goo Goo Dolls', 'en-US'
master_playlist.tracks.append(track5)


ipod.write_db()

Or use existing command-line tool teresa to manage your player:

teresa

“teresa” is a command line tool, and has few sub commands.

usage: teresa [-h] [-v] <command> ...

optional arguments:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit

commands:
  <command>
    set          set voiceover enable or disable, set max volume
    show         show ipod low level DB
    sync         sync to ipod

Try 'teresa <command> -h' for command help.

show

usage: teresa show [-h] -b <path>

optional arguments:
  -h, --help  show this help message and exit
  -b <path>   ipod base path

Example of use:
  teresa show -b /media/ipod_base

set

usage: teresa set [-h] -b <path> [-v <bool>] [-m <int>]

optional arguments:
  -h, --help  show this help message and exit
  -b <path>   ipod base path
  -v <bool>   enable or disable voiceover, true for enable, false for disable
  -m <int>    max volume, 0 is do not limit

Example of use:
  teresa set -b /media/ipod_base -v true -m 15

sync

usage: teresa sync [-h] -b <path> -s <path> [-l <langs>] [-e <engine>]
                   [-k <key>] [-f <format>]

optional arguments:
  -h, --help   show this help message and exit
  -b <path>    ipod base path
  -s <path>    source path
  -l <langs>   comma-separated set of target language codes, e.g en-gb,zh-cn
  -e <engine>  TTS engine, voicerss or svox

Legal lang codes of engines:
  voicerss: ca-es, da-dk, de-de, en-au, en-ca, en-gb, en-in, en-us, es-es, es-mx, fi-fi, fr-ca, fr-fr, it-it, ja-jp, ko-kr, nb-no, nl-nl, pl-pl, pt-br, pt-pt, ru-ru, sv-se, zh-cn, zh-hk, zh-tw
  svox: de-de, en-gb, en-us, es-es, fr-fr, it-it

Two examples of use:
  teresa sync -b /media/ipod_base -s /media/ipod_src -l en-gb -e svox
  teresa sync -b /media/ipod_base -s /media/ipod_src -l en-gb,zh-cn,ja-jp -e voicerss -k d279f919f7384d3bafa516caad0eae56

Source path folder structure see: http://ipodshuffle.readthedocs.org/en/latest/teresa/index.html#source-path-folder-structure
TTS engines

Program use langid to identify title text langguage of track and playlist, but not work perfectly, It is suggested that you use “-l lang1,lang2…” to specify languages range.

For now, have two TTS engine wrapper:

svox
CLI command is “pico2wave”, if you want to use it, make sure you have already installed it.
voicerss
An http engine. It supports lot of languages(include CJK). For now, dayily request is free for 350 times, but need to register on the website to get an API key, website: http://www.voicerss.org
source path folder structure

All folders and audio files can be symbolic(soft) links.

“source” is just a example, you can use another name whatever you want. In source folder, only three folders will be scanned: “music”, “podcasts” and “audiobooks”.

Under “music”, all folders(include children folders and children’s children folders and so on) are NORMAL playlists. NORMAL playlist also caontain their child folder tracks. MASTER playlist contain all tracks of all NORMAL playlists

Under “podcasts”, only folders will be PODCAST playlists.

Under “audiobooks”, files and folders will be AUDIOBOOK playlists, but folder’s child folder wouldn’t.

See example folders structure following and notice the IGNORED folders and IGNORED audio files:

source
   ├── music
   │      ├── English songs
   │      │      ├── Bob Dylan
   │      │      │      ├── Bob Dylan - Farewell.mp31
   │      │      │      └── Bob Dylan - Mr. Tambourine Man.mp3
   │      │      │
   │      │      └── Mariah Carey
   │      │             ├── Mariah Carey - Bye Bye.mp3
   │      │             └── Mariah Carey - Hero.mp3
   │      │
   │      ├── 邓丽君
   │      │      ├── 邓丽君 - 小城故事多.mp3
   │      │      ├── 邓丽君 - 何日君再来.mp3
   │      │      └── 邓丽君 - 恰似你的温柔.mp3
   │      │
   │      ├── The Clash - Bankrobber.mp3
   │      ├── The Weepies - Gotta Have You.mp3
   │      ├── 梁静茹 - 小手拉大手.mp3
   │      ├── 卢冠廷 - 一生所爱.mp3
   │      └── 喜納昌吉 - 花~すべての人の心に花を.mp3
   │
   │
   ├── podcasts
   │      ├── 6 Minute English
   │      │      ├── p03fgnf9.mp3
   │      │      ├── p03g4kll.mp3
   │      │      ├── p03gtsz8.mp3
   │      │      └── p03hj7dq.mp3
   │      │
   │      ├── The English We Speak
   │      │      ├── p03gmjw3.mp3
   │      │      ├── p03hb15j.mp3
   │      │      └── p03j16wv.mp3
   │      │
   │      ├── Luk's ENGLISH Podcast
   │      │      ├── FOLDER_IN_THIS_LEVEL_WILL_BE_IGNORED
   │      │      │      └── THIS_AUDIO_WILL_BE_IGNORED.mp3
   │      │      │
   │      │      ├── 326-catching-up-with-oli-future-predictions-part-2.mp3
   │      │      ├── 327-the-lep-photo-competition-please-check-out-the-photos-and-vote.mp3
   │      │      └── 328-cooking-with-luke-verbs-and-expressions-in-the-kitchen.mp3
   │      │
   │      │
   │      └── AUDIO_IN_THIS_LEVEL_WILL_BE_IGNORED.mp3
   │
   │
   └── audiobooks
          ├── 01.Love Or Money
          │      ├── 01.mp3
          │      ├── 02.mp3
          │      ├── 03.mp3
          │      ├── 04.mp3
          │      ├── 05.mp3
          │      ├── 06.mp3
          │      └── 07.mp3
          │
          │
          ├── 02.Mary Queen Of Scots
          │      ├── FOLDER_IN_THIS_LEVEL_WILL_BE_IGNORED
          │      │      └── THIS_AUDIO_WILL_BE_IGNORED.mp3
          │      │
          │      ├── 01.Fotheringhay.mp3
          │      ├── 02.France.mp3
          │      ├── 03.Darnley and Riccio.mp3
          │      ├── 04.The death of David Riccio.mp3
          │      ├── 05.My son is born.mp3
          │      ├── 06.Kirk O'Field.mp3
          │      ├── 07.Bothwell.mp3
          │      ├── 08.England.mp3
          │      └── 09.A Death.mp3
          │
          ├── a book in single audio.mp3
          └── another book in single audio.mp3