A program that simplifies the process of searching, downloading and converting Youtube videos to MP3 files from the command-line.

Overview¶

All you need is the video URL or the name of the artist/track you’re looking for. The program will attempt to retrieve data for a song matching the provided input by querying the iTunes API and use the data to find a corresponding YouTube video, if a URL is not provided. The video will then be downloaded, converted, and the gathered data will be used to populate the metadata of the MP3.

Note

If a URL is provided and no match is found for the song data, the program will prompt the user for the title/artist and the YouTube thumbnail will be used as the album artwork.

Contributing¶

If you’d like to contribute to the project, feel free to suggest a feature request and/or submit a pull request.

Contents¶

Getting Started¶

Install¶

You can install the program with the following command:

$ pip install yt2mp3

Prerequisites¶

The program only requires that you have Python 3.4+ and ffmpeg or libav installed. More installation information is available on the additional setup page.

Usage¶

Once installed, the program can be executed via the command-line as follows:

$ yt2mp3 [-options]

When the program is finished, you can find the resulting MP3 file in your Downloads directory, with the following file-structure Music/{artist}/{track}.mp3.

Options¶

`-t, --track`	Specify the track name query
`-a, --artist`	Specify the artist name query
`-c, --collection`	Specify the album name query
`-u, --url`	Specify a Youtube URL or ID
`-u, --url`	Specify a Youtube URL or ID
`-p, --playlist`	Specify a Youtube playlist URL or ID
`-o, --overwrite`	Overwrite the file if one exists in output directory
`-r, --resolution`	Specify the resolution for the cover-art
`-q, --quiet`	Suppress program command-line output
`-v, --verbose`	Display a command-line progress bar
`--version`	Show the version number and exit
`-h, --help`	Display information on usage and functionality

Contributing¶

If you’d like to contribute to the project, you can download and install the program with the following commands:

# Clone the repository
$ git clone https://github.com/tterb/yt2mp3

# Navigate to the directory
$ cd yt2mp3

# Install program dependencies
$ pip install -r requirements.txt

Additional Setup¶

The project utilizes the pydub package for audio-file manipulation, which requires that a multimedia decoding library to function properly. You can use ffmpeg or libav.

Mac (using homebrew)¶

# ffmpeg
brew install ffmpeg --with-libvorbis --with-sdl2 --with-theora

####    OR    #####

# libav
brew install libav --with-libvorbis --with-sdl --with-theora

Linux (using aptitude)¶

# libav
apt-get install libav-tools libavcodec-extra-53

####    OR    #####

# ffmpeg
apt-get install ffmpeg libavcodec-extra-53

Windows¶

Download and extract libav from Windows binaries provided here.

Add the libav /bin folder to your PATH

Changelog¶

Version 1.2.4¶

Improved optimal video retrieval by utilizing video and track lengths
Normalized function and variable naming-conventions
Added missing function docstrings
Updated project dependencies

Version 1.2.3¶

Improved package CLI
Modified requests version to avoid a potential security vulnerability
Fixed #22 - Python 3.4 compatibility
Modified package to use youtube-dl for downloading videos
Enhancement #17 - Added option to specify album name

Version 1.2.0¶

Improved package file-structure
Enhancement #16 - Added custom cover-art resolution option
Improved default cover-art resolution
Added validation check for YouTube URLs
Improved command-line option parsing
Improved package test coverage and logging
Improved song data acquisition processes
Integrated Codecov code coverage
Improved playlist overwrite handling
Improve temporary file clean-up on SystemExit and KeyboardInterrupt
Removed unnecessary code/comments

Version 1.1.0¶

Added support for playlists
Improved command-line option functionality
Added duplicate check and overwrite command-line option
Added Travis CI integration testing
Improved cover-art resolution
Improved compatibility for Python < 3.6 versions
Improved ID3 tag embedding processes

Version 1.0.5¶

Added additional error-handling
Improved song data acquisition for YouTube URLs
Improved command-line option functionality
Added additional package documentation
Fixed issue with missing executable from PyPi

Version 1.0.2¶

Published package to PyPi

Version 1.0.0¶

All features added
All bugs created

Contributing¶

The following is a set of guidelines for contributing to this project. These are not rules, use your best judgment and feel free to propose changes to this document in a pull request.

Code of Conduct¶

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior here.

How Can I Contribute?¶

Reporting Bugs¶

This section guides you through submitting a bug report for Atom. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

Before creating bug reports, please check the existing issues as you might find out that one has already been created by another user.
When you are creating a bug report, please provide a clear and descriptive title.
Please include as many details as possible in your report. Remember, in order to fix the issue, we must first be able to reproduce it.
The use of images, GIFs, or any other form of media is not only allowed, it’s encouraged.
Include any relevant details about your configuration and environment.

Enhancements & Feature Requests¶

Users provide the best insight for improving a product. So always feel free to suggest improvements, feedback, and give the developers an idea of what new features you’d like to see in the future. Don’t forget, this is one of the greatest benefits of open-source development! If you’d like to submit an enhancement request, please include the following information: * Current project version (check that you are using the latest version) * How would this enhancement benefit most users? * Do you have any examples of other applications that feature this enhancement? * Relevant details about your configuration and environment. * Note: Don’t forget to tag your post with the Enhancement label.

Pull Requests¶

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

Provide as much information as possible on the changes made to existing code.
Include thoughtfully-worded, well-structured commit messages and comments.
Include screenshots and animated GIFs in your pull request whenever possible.
When addressing an existing issue, please include an issue mention in the description of your pull request.
End files with a newline.
Avoid platform-dependent code on cross-platform applications.
Ensure that submitted code follows the style guidlines specified in the Styleguide below.

Styleguides¶

Commit Messages¶

Do your best to conform the tense to that of the existing commits. (“Add feature” not “Added feature” or vice versa)
Use the imperative mood (“Move cursor to…” not “Moves cursor to…”)
Consider starting the commit message with an applicable emoji:
- :art: when improving the format/structure of the code
- :racehorse: when improving performance
- :memo: when writing docs
- :penguin: when fixing something on Linux
- :apple: when fixing something on macOS
- :checkered_flag: when fixing something on Windows
- :bug: when fixing a bug
- :recycle: when refactoring code
- :fire: when removing code or files
- :white_check_mark: when adding tests
- :lock: when dealing with security
- :iphone: when working on responsive design
- :truck when moving or renaming files
- :bento: when adding or updating assets
- :building_construction: when making architectural changes
- :wheelchair: when improving accessibility
- :construction_worker: when modifying the CI build
- :non-potable_water: when plugging memory leaks
- :arrow_up: when upgrading dependencies
- :arrow_down: when downgrading dependencies
- :rotating_light: when removing linter warnings

Code¶

Use spaces around operators
- count + 1 instead of count+1
Capitalize initialisms and acronyms in names, except for the first word, which should be lower-case:
- getURL instead of getUrl
Provide comments for important or complex code
Conform your code to the existing styles to the best of your ability
Always check that your submission follows The Boy Scout Rule

The MIT License (MIT)¶

MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

License taken from MIT license.

Overview¶

Contributing¶

Contents¶

Getting Started¶

Install¶

Prerequisites¶

Usage¶

Options¶

Contributing¶

Additional Setup¶

Mac (using homebrew)¶

Linux (using aptitude)¶

Windows¶

Changelog¶

Version 1.2.4¶

Version 1.2.3¶

Version 1.2.0¶

Version 1.1.0¶

Version 1.0.5¶

Version 1.0.2¶

Version 1.0.0¶

Contributing¶

Code of Conduct¶

How Can I Contribute?¶

Reporting Bugs¶

Enhancements & Feature Requests¶

Pull Requests¶

Styleguides¶

Commit Messages¶

Code¶

The MIT License (MIT)¶

Indices and tables¶