| Name | musicscan JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | None |
| Summary | Package for converting music metadata to XML |
| upload_time | 2024-08-19 00:04:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >3.8 |
| license | MIT License |
| keywords |
xml
music
cds
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# musicscan - Music File Scanner
The `musicscan` package is a software library for extracting metadata from a digital
music collection and builds a set of XML files adhering to the vtmedia schema.
It includes a tool that will recursively scan a directory for audio files
containing ID3 tags and uses that data as the basis for bulding XML files.
* [How It Works](#how-it-works)
* [XML Schema](#xml-schema)
* [Scanning Example](#scanning-example)
* [The Audio CD File](#the-audio-cd-file)
* [The Index File](#the-index-file)
* [The Album File](#the-album-file)
* [Documentation](#documentation)
* [Building And Installing From Source Code](#building-and-installing-from-source-code)
* [Package Distribution](#package-distribution)
## How It Works
It works under the assumption that the digital library was created by importing CDs
into a music ecosystem like iTunes or Windows Media Player; so it uses
the nomenclature of physical CDs. That is, every audio file scanned represents
a single track that was imported from a physical Compact Disc, and it will
use the metadata to build the XML files. If the metadata does not include
information like track number, or disc number; the import will probably not work.
The benefits of extracting the metadata are:
1. Maintaining a separate copy of the metadata away from the music library.
2. Extending the metadata with extra fields that may not be supported with ID3 tags.
3. Searching the metadata with tools that may not be available to your music player.
4. Sharing the metadata with other users.
## XML Schema
The XML generated from the tool adheres to the VTMedia schema, which can be found here.
| Repository | Purpose |
| --- | --- |
| [vtmedia-schema](https://github.com/cjcodeproj/vtmedia-schema) | Schema and XML validation for media data |
The schema can be loaded into command line tools, IDEs, or custom code applications to examine
the validity of the metadata files. It also contains example music data that has been generated
using the `id3tool` code, and then edited for accuracy.
## Scanning Example
If you have a directory like this.
```
$ ls -1 "~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences/"
01 The Thunder Rolls.m4a
02 New Way To Fly.m4a
03 Two Of A Kind, Workin' On A Full House.m4a
04 Victim Of The Game.m4a
05 Friends In Low Places.m4a
06 Wild Horses.m4a
07 Unanswered Prayers.m4a
08 Same Old Story.m4a
09 Mr. Blue.m4a
10 Wolves.m4a
```
The `id3scan` tool will search that directory and create three files. Make sure the install path for the id3scan tool
matches your environment command path.
```
$ id3scan --musicpath "~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences" --write --outdir ~/tmp --split-xml
```
```
$ ls -1 ~/tmp/
garth_brooks_no_fences-1990-album.xml
garth_brooks_no_fences-1990-audiocd.xml
garth_brooks_no_fences-1990-cd01-index.xml
```
Each file contains different aspects of the album data.
| File | Data |
|------|------|
| garth_brooks_no_fences-1990-audiocd.xml | Information on the physical media |
| garth_brooks_no_fences-1990-album.xml | Information about each song |
| garth_brooks_no_fences-1990-cd01-index.xml | Track order information for each song |
The XML files are nested together with XInclude directives tying them together. If a user skips the `---split-xml` diretive, only
one output file is generated.
### The Audio CD file
The audio cd file is the main file of the data structure. Most of the relevant information is on the
physical CD structure.
```
<medialist xmlns='http://vectortron.com/xml/media/media' xmlns:xi='http://www.w3.org/2001/XInclude'>
<!-- created by id3scan (2024-04-06 15:33:06.931311) -->
<media>
<title>
<main>No Fences</main>
</title>
<medium>
<release>
<type><audiocd/></type>
</release>
<productSpecs>
<inventory>
<case>
<cd id='cd01'/>
</case>
</inventory>
</productSpecs>
</medium>
```
### The Index File
The index file contains information about track order, with references to the songs on the album.
```
<cdIndex ref='cd01' xmlns='http://vectortron.com/xml/media/media'>
<track no='1'>
<index no='01'>
<content ref='ttr01'/>
</index>
</track>
...
```
### The Album File
The album file contains all of the information about the songs.
```
<album xmlns='http://vectortron.com/xml/media/audio'>
<title>No Fences</title>
<catalog>
<artists>
<artist><unkn>Garth Brooks</unkn></artist>
</artists>
</catalog>
<classification>
<genres>
<primary>Country</primary>
</genres>
</classification>
<elements>
<song id='w01'>
<title>
<main>Wolves</main>
</title>
<catalog>
<composers>
<composer><unkn>Stephanie Davis</unkn></composer>
</composers>
</catalog>
<technical>
<studioRecording/>
<runtime>
<overall>PT4M8.89S</overall>
</runtime>
</technical>
</song>
...
```
## Documentation
There is RST documentation for the [id3scan.rst](doc/id3scan.rst) tool in the [doc](doc/) directory.
There is an [EDITING.md](EDITING.md) file with documentation on how to edit the XML generated by
the `id3scan` code.
## Building And Installing From Source Code
Assuming a normal Python 3 environment with setuptools and build modules
installed, run the build module in the top level directory of the repository.
```
$ cd musicscan
$ python -m build
```
This code has a dependency on the [TinyTag](https://pypi.org/project/tinytag/)
module, which should automatically be installed during the build process.
## Package Distribution
[](https://pypi.org/project/musicscan/)
Installation can be done through the python pip command.
```
$ python -m pip install --user musicscan
```
Raw data
{
"_id": null,
"home_page": null,
"name": "musicscan",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.8",
"maintainer_email": null,
"keywords": "xml, music, cds",
"author": null,
"author_email": "Chris J <cjcodeproj@fastmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8e/e0/bbd4663896db2fe52763359ff179701dba017e3dd8f13f85390acc37bfd9/musicscan-0.1.7.tar.gz",
"platform": null,
"description": "# musicscan - Music File Scanner\n\nThe `musicscan` package is a software library for extracting metadata from a digital\nmusic collection and builds a set of XML files adhering to the vtmedia schema.\n\nIt includes a tool that will recursively scan a directory for audio files\ncontaining ID3 tags and uses that data as the basis for bulding XML files.\n\n\n * [How It Works](#how-it-works)\n * [XML Schema](#xml-schema)\n * [Scanning Example](#scanning-example)\n * [The Audio CD File](#the-audio-cd-file)\n * [The Index File](#the-index-file)\n * [The Album File](#the-album-file)\n * [Documentation](#documentation)\n * [Building And Installing From Source Code](#building-and-installing-from-source-code)\n * [Package Distribution](#package-distribution)\n\n\n## How It Works\n\nIt works under the assumption that the digital library was created by importing CDs\ninto a music ecosystem like iTunes or Windows Media Player; so it uses \nthe nomenclature of physical CDs. That is, every audio file scanned represents\na single track that was imported from a physical Compact Disc, and it will\nuse the metadata to build the XML files. If the metadata does not include \ninformation like track number, or disc number; the import will probably not work.\n\nThe benefits of extracting the metadata are:\n\n1. Maintaining a separate copy of the metadata away from the music library.\n2. Extending the metadata with extra fields that may not be supported with ID3 tags.\n3. Searching the metadata with tools that may not be available to your music player.\n4. Sharing the metadata with other users.\n\n## XML Schema\n\nThe XML generated from the tool adheres to the VTMedia schema, which can be found here.\n\n| Repository | Purpose |\n| --- | --- |\n| [vtmedia-schema](https://github.com/cjcodeproj/vtmedia-schema) | Schema and XML validation for media data |\n\nThe schema can be loaded into command line tools, IDEs, or custom code applications to examine\nthe validity of the metadata files. It also contains example music data that has been generated\nusing the `id3tool` code, and then edited for accuracy.\n\n## Scanning Example\n\nIf you have a directory like this.\n\n```\n$ ls -1 \"~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences/\"\n01 The Thunder Rolls.m4a\n02 New Way To Fly.m4a\n03 Two Of A Kind, Workin' On A Full House.m4a\n04 Victim Of The Game.m4a\n05 Friends In Low Places.m4a\n06 Wild Horses.m4a\n07 Unanswered Prayers.m4a\n08 Same Old Story.m4a\n09 Mr. Blue.m4a\n10 Wolves.m4a\n```\n\nThe `id3scan` tool will search that directory and create three files. Make sure the install path for the id3scan tool\nmatches your environment command path.\n\n```\n$ id3scan --musicpath \"~/Music/iTunes/iTunes Media/Music/Garth Brooks/No Fences\" --write --outdir ~/tmp --split-xml\n```\n\n```\n$ ls -1 ~/tmp/\ngarth_brooks_no_fences-1990-album.xml\ngarth_brooks_no_fences-1990-audiocd.xml\ngarth_brooks_no_fences-1990-cd01-index.xml\n```\n\nEach file contains different aspects of the album data.\n\n| File | Data |\n|------|------|\n| garth_brooks_no_fences-1990-audiocd.xml | Information on the physical media |\n| garth_brooks_no_fences-1990-album.xml | Information about each song |\n| garth_brooks_no_fences-1990-cd01-index.xml | Track order information for each song |\n\nThe XML files are nested together with XInclude directives tying them together. If a user skips the `---split-xml` diretive, only\none output file is generated.\n\n### The Audio CD file\n\nThe audio cd file is the main file of the data structure. Most of the relevant information is on the\nphysical CD structure.\n\n```\n<medialist xmlns='http://vectortron.com/xml/media/media' xmlns:xi='http://www.w3.org/2001/XInclude'>\n <!-- created by id3scan (2024-04-06 15:33:06.931311) -->\n <media>\n <title>\n <main>No Fences</main>\n </title>\n <medium>\n <release>\n <type><audiocd/></type>\n </release>\n <productSpecs>\n <inventory>\n <case>\n <cd id='cd01'/>\n </case>\n </inventory>\n </productSpecs>\n</medium>\n```\n\n### The Index File\n\nThe index file contains information about track order, with references to the songs on the album.\n\n```\n<cdIndex ref='cd01' xmlns='http://vectortron.com/xml/media/media'>\n <track no='1'>\n <index no='01'>\n <content ref='ttr01'/>\n </index>\n</track>\n...\n```\n\n### The Album File\n\nThe album file contains all of the information about the songs.\n\n```\n<album xmlns='http://vectortron.com/xml/media/audio'>\n <title>No Fences</title>\n <catalog>\n <artists>\n <artist><unkn>Garth Brooks</unkn></artist>\n </artists>\n </catalog>\n <classification>\n <genres>\n <primary>Country</primary>\n </genres>\n </classification>\n <elements>\n <song id='w01'>\n <title>\n <main>Wolves</main>\n </title>\n <catalog>\n <composers>\n <composer><unkn>Stephanie Davis</unkn></composer>\n </composers>\n </catalog>\n <technical>\n <studioRecording/>\n <runtime>\n <overall>PT4M8.89S</overall>\n </runtime>\n </technical>\n </song>\n...\n```\n\n## Documentation\n\nThere is RST documentation for the [id3scan.rst](doc/id3scan.rst) tool in the [doc](doc/) directory.\n\nThere is an [EDITING.md](EDITING.md) file with documentation on how to edit the XML generated by\nthe `id3scan` code.\n\n## Building And Installing From Source Code\n\nAssuming a normal Python 3 environment with setuptools and build modules\ninstalled, run the build module in the top level directory of the repository.\n\n```\n$ cd musicscan\n$ python -m build \n```\n\nThis code has a dependency on the [TinyTag](https://pypi.org/project/tinytag/)\nmodule, which should automatically be installed during the build process.\n\n## Package Distribution\n\n[](https://pypi.org/project/musicscan/)\n\nInstallation can be done through the python pip command.\n\n```\n$ python -m pip install --user musicscan\n```\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Package for converting music metadata to XML",
"version": "0.1.7",
"project_urls": {
"bug tracker": "https://github.com/cjcodeproj/musicscan/issues",
"changelog": "https://github.com/cjcodeproj/musicscan/blob/main/CHANGELOG.md",
"homepage": "https://github.com/cjcodeproj/musicscan",
"repository": "https://github.com/cjcodeproj/musicscan"
},
"split_keywords": [
"xml",
" music",
" cds"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a7f37f34828c7ee36f5885bad8bb541b124b766ec2c7ef6f9c4b87503465cdd5",
"md5": "54940ad76bc9c3fbb02264e9990fa2a3",
"sha256": "0c687cd5640e492ff11ca30c09fd5841859d72c5fb3f2c1b7ae9659f9dcb337e"
},
"downloads": -1,
"filename": "musicscan-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54940ad76bc9c3fbb02264e9990fa2a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.8",
"size": 37815,
"upload_time": "2024-08-19T00:04:30",
"upload_time_iso_8601": "2024-08-19T00:04:30.297583Z",
"url": "https://files.pythonhosted.org/packages/a7/f3/7f34828c7ee36f5885bad8bb541b124b766ec2c7ef6f9c4b87503465cdd5/musicscan-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ee0bbd4663896db2fe52763359ff179701dba017e3dd8f13f85390acc37bfd9",
"md5": "043f04086a8c04b379b38f57e5deacc8",
"sha256": "623e087f1c90e0f139b98a87d9c237356458780cd797e183c6c1e244b37cd3e2"
},
"downloads": -1,
"filename": "musicscan-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "043f04086a8c04b379b38f57e5deacc8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.8",
"size": 22493,
"upload_time": "2024-08-19T00:04:31",
"upload_time_iso_8601": "2024-08-19T00:04:31.700168Z",
"url": "https://files.pythonhosted.org/packages/8e/e0/bbd4663896db2fe52763359ff179701dba017e3dd8f13f85390acc37bfd9/musicscan-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-19 00:04:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cjcodeproj",
"github_project": "musicscan",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "musicscan"
}
