Skip to content

Latest commit

 

History

History
196 lines (125 loc) · 7.04 KB

README_EN.md

File metadata and controls

196 lines (125 loc) · 7.04 KB
Raw

中文介绍

Table of contents

(toc is generated by ghtoc)

Introduction

zhuaxia(抓虾) (MIT Licensed) is a little tool to batch download music resources in multiple threads from www.xiami.com (in short [xia]) and music.163.com (in short [163]).

zhuaxia was written and tested with:

  • python 2.7.6

Dependencies

  • requests module
  • mutagen module
  • beautifulsoup4 module
  • pycrypto module

Features

  • automatically recognize and parse URLs, so far it supports:
    • [xia] Song, Album, Collections, User Favorites, Artist TopN
    • [163] Song, Album, Playlist, Artist TopN
  • artist Top N(configurable) Songs.(if value <=0, download all top songs of the artist. [xia]only songs on the first page will be downloaded), default Top10. Configuration property: download.artist.topsong artist page url is needed
  • download mixed urls in file. URLs can be mixed by [xia] and [163], also they can be different resource types (-f option)
  • when download from file, multi-threading parsing the urls with a configurable thread pool
  • multi-threading download with configurable thread pool.
  • download HQ (320kbps) resources (-H option)
  • user friendly downloading progress display (colorful highlighting, adapt terminal width automatically, total progress, downloading thread progress...)
  • mp3 renaming, mp3 meta data updating, auto-download album cover image. Album description(only[xia])...
  • configuration property china.proxy.http=ip:port for resource downloading via China proxy. Details："Usage -> download resource outside China"
  • -p option (experimental function)，using a proxypool to solve the problem of "ip was banned if requests to a server were too often.
  • Chinese (default) or English CLI, add lang=en in config file to change CLI into English.
  • Download lyrics (-l option)
  • since v3.0.0 zhuaxia maintains a download history, supports incremental downloading. (-i option). When running with -i, mp3 in history will be skipped.
  • supports Export (-e), Clear (-d) download history function
  • provides download summary after all downloading finished, supports view/save summary.

Installation

Archlinux user, zhuaxia can be found in AUR

Stable version (master branch):

yaourt -S zhuaxia

latest git version (bleeding branch):

yaourt -S zhuaxia-git

other users:

sudo python setup.py install

Usage

  • configuration file: after first time running zx, zhuaxia.conf will automatically generated under $HOME/.zhuaxia/ check the comment in config file for details

  • Usage:

      zhuaxia -- download mp3 music from [xiami.com] and [music.163.com]

  [CONFIG FILE:]  $HOME/.zhuaxia/zhuaxia.conf
  				It will be automatically created when zhuaxia was started first time.

  [OPTIONS]
  	-H : prefer High Quality(320kbps),
  		> xiami <
  			- xiami vip user email/password should be set in config
  			- user should set HQ on xiami vip setting page
  			- if any above requirements was not satisfied, 128kbps will be taken
  		> 163 <
  			- no special requirement

  	-h : show this help

  	-l : download lyric too (lrc format)

  	-f : download from url file (see example in [USAGE])

  	-i : incremental downloading
  		 zhuaxia will check download history and skip the mp3 if it has been downloaded before.
  		 To identify a downloaded mp3, the combination of these three attributes will be checked:
  		 song_id(id in xiami/netease), source (xiami/netease), quality (H/L)

  	-e : export history data to file, if this option was given, other options will be ignored.

  	-d : clear all history data, if this option was given, other options will be ignored.
  		 -e and -d cannot be used together.

  	-v : show version information

  	-p : auto choose proxy from proxy pool (experimental option)
  		 when frequency of request to target host is high enough, host could ban the client
  		 for some time. zhuaxia will auto take proxy from pool. However this may make
  		 downloading slow or unstable.

  [USAGE]

  	zx [OPTION] <URL>

  		 auto recognize and download the given url resource, supports:
  			- [xm] song, album, favorite, collection, artist TopN
  			- [163]song, album, list, artist topN

  	Example:
  			zx "http://www.xiami.com/space/lib-song/u/25531126"
  			zx "http://music.163.com/song?id=27552647"

  	zx [OPTION] -f <file>

  		download from url file. one url per line. The urls could be 163 and xm mixed. Example:

  	Example:
  		  $ cat /tmp/foo.txt
  			http://music.163.com/artist?id=5345
  			http://www.xiami.com/song/1772130322
  			http://music.163.com/album?id=2635059
  			http://www.xiami.com/album/32449

  		  $ zx -f /tmp/foo.txt

  	Other Examples:

  			download lyrics with songs: 
  				zx -l "http://music.163.com/song?id=27552647"

  			incremental download songs with lyrics: 
  				zx -li "http://music.163.com/song?id=27552647"

  			export zhuaxia download history. File will be save under "download.dir" in config file:
  				zx -e

  			clear(delete) all zhuaxia download history:
  				zx -d

Proxy setting

Download Xiami resources outside China

Both xiami.com and music.163(Netease) block http Requests from IP addresses outside China. For 163 resources, zhuaxia uses a url that so far (2015-11-12) still working for oversea IP direct downloading. However this won't last long. For stable usage, please read the below section about the proxy option.

In configuration file adding property (if it doesn't exist): china.proxy.http=ip:port (before it was called xiami.proxy.http) can let zhuaxia download resources via proxy.

For example:

china.proxy.http=127.0.0.1:8080

The ip:port is http proxy in China, so that we can send request with Chinese IP. If your machine has already an IP in China. You don't need this option. You can remove or comment this property out.

Tip: finding a China proxy:

Considering the users' existing config, the option xiami.proxy.http is still usable too. The proxy will be applied for both xiami and 163 song downloading. However changing the option name in config is recommended. Old and new options cannot be used together.

How to get China Proxy

Go to http://proxy-list.org/ then search country "China"

Or:

Using this script: cnProxy.py to get top N (default 5) fast China Proxies.

Screenshots

  • parsing and multi-thread downloading (gif animation) progress

  • multi-thread parsing input file (gif animation) file view

  • parse url url view

Changelog

Click to check Change logs