Skip to main content

create dream-sequences from your video browsing history

Project description


tubedreams is part of material browsing history, an experiment in self-quantification and imagining different ways of engaging with computation, privacy, consumption and personal data.

tubedreams is a command line program that concatenates random pieces of local or online videos with the intention of making collages of videos you have viewed. In its default settings, tubedreams turns your YouTube viewing history into new video content. Unrelated sequences of images and sound are recombined in playful or nightmarish ways that could only be produced via your own uniquely-curated media consumption. It can also be adapted for other purposes of making quick video collages (see examples).


As well as a few python packages, which should automatically get installed when this package is installed:

  • youtube-dl -- for grabbing videos from YouTube or another site.

  • moviepy -- for cutting video (uses ffmpeg as a backend).

  • pysox, a python wrapper for SoX -- for audio effects


pip install tubedreams


By default, tubedreams attempts to access your YouTube history as a playlist via youtube-dl. In order for youtube-dl to access your history like your browser does, you need to configure your login information in one of three ways:

  • Setup the .tubedreams.conf file in the package directory (tubedreams looks for this by default).

  • Add your login information to a .netrc file (and pass the --netrc argument):

    touch ~/.netrc
    chmod 600 ~/.netrc
    echo "machine youtube login LOGIN password PASSWORD" >> ~/.netrc
    # verify that the login information is correct
    tubedreams --netrc --number 1 --length 5 --minmax 5 --fresh --output test.mp4
  • Or pass your login information manually via the --login USERNAME PASSWORD argument.

note: If you have two-factor authentication set-up with your YouTube/Google account, you will be required to manually authenticate since youtube-dl does not support interfacing with the YouTube developer API.

For public playlists, searches or individual videos, you can pass the argument --nologin to avoid having to setup authentication.


usage: tubedreams [-h] [-v] [-dd] [-s [[...]]] [-p ] [-f] [-o ] [-k] [-u ]
                  [-n ] [-da] [-N] [-L [[...]]] [-nl] [-l ] [-m [[...]]]
                  [-fc ] [-g] [-x] [-r [[...]]] [-c ] [-a ] [-oa] [-dp] [-vf ]

create dream-sequences from your video browsing history

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -dd, --dontdownload   don't download any videos or connect to youtube-dl.
                        will only use local videos from source directories.
  -s [ [ ...]], --source [ [ ...]]
                        specify directories to draw raw footage from. the
                        first directory listed also specifies the location for
                        new videos to download
  -p [], --pattern []   only use videos from input directories which contain a
                        given string. note: will still download raw videos
                        that do not match pattern.
  -f, --fresh           only include videos downloaded this run
  -o [], --output []    specify file name and directory for final video output
  -k, --keep            keep raw downloaded videos after processing is

youtube-dl options:
  -u [], --url []       the url of the playlist, search page, or video to
                        download from. default is to grab history from
  -n [], --number []    number of videos to download
  -da, --downloadall    download all videos in playlist. overrides -n
  -N, --netrc           use .netrc file for login instead of .tubedreams.conf
  -L [ [ ...]], --login [ [ ...]]
                        username and password for accessing YouTube or other
                        site via youtube-dl.
  -nl, --nologin        do not log into an account to access site

video output options:
  -l [], --length []    total length of video to output
  -m [ [ ...]], --minmax [ [ ...]]
                        minimum and maximum length of each clip. one input
                        fixes a static clip length. two inputs sets range.
  -fc [], --finalclip []
                        specify length of final clip
  -g, --grow            scale length of clips so that they gradually get
                        longer or shorter to match finalclip. must use with
  -x, --exponential     makes length scaling exponential. must use with grow.
  -r [ [ ...]], --resolution [ [ ...]]
                        select dimensions to output to. one input specifies y
                        dimension for 12:9 ratio. for two inputs, the smaller
                        specifies y and the larger specifies x. default is
  -c [], --codec []     choose codec for uncommon video format or override
                        default codec. defaults are included for mp4
                        (libx264), mkv (libx264), webm (libvpx), ogv
                        (libvorbis) and avi (png).
  -a [], --setaudio []  add path to audio track to use
  -oa, --onlyaudio      only export to mp3 audio, no video.
  -dp, --dontprocessaudio
                        keep raw audio and do not apply sox filters.
  -vf [], --videofilters []
                        add ffmpeg video filters to output video.


See the ffmpeg documentation for a list of native ffmpeg filters and usage syntax. You can invoke ffmpeg video filters in tubedreams with -vf just as you would with ffmpeg:

-vf eq=brightness=.3:contrast=2:gamma=.6:saturation=0,fade=in:0:60

Complex filters and audio filters are not currently supported.

Downloading Videos

See this list for sites currently supported by youtube-dl. Note that not all of these supported sites will necessarily have playlist features fully implemented. For non-YouTube sites, it could be necessary to create a work-around to capture videos in history or playlists even if they appear in this list.


Download five random videos from your YouTube history, keep them, and chop and recombine into a 20 second clip:

tubedreams --number 5 --fresh --keep --length 20 --minmax 1 3 --output test.mp4

A random 10 second clip from your YouTube history:

tubedreams --number 1 --fresh --length 10 --minmax 10 --dontprocessaudio --output 10sec.avi

Download your entire YouTube history and turn it into a 5-hour-long sound collage for an art exhibition:

tubedreams --downloadall --onlyaudio --length 18000 --minmax .2 10 --output experimental.mp3

Cut clips from local video files and make into black-and-white:

tubedreams --dontdownload --source ~/Videos/movies/ ~/Videos/shows/ --videofilters "eq=saturation=0:gamma=.5:contrast=2:brightness=.2" --length 120 --minmax 10 --output bw.mkv

The news in 30 seconds:

tubedreams --url "" --nologin --downloadall --fresh --length 30 --minmax .1 .5 --videofilters eq=saturation=5:contrast=2,random --dontprocessaudio --output news.ogv

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tubedreams-0.3.0.tar.gz (9.6 kB view hashes)

Uploaded source

Built Distribution

tubedreams-0.3.0-py3-none-any.whl (10.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page