{"id":15293700,"url":"https://github.com/spongebobsun/holophonor","last_synced_at":"2025-04-13T14:08:29.654Z","repository":{"id":56914572,"uuid":"169520510","full_name":"SpongeBobSun/Holophonor","owner":"SpongeBobSun","description":"Convenience library for managing \u0026 querying music on iOS devices","archived":false,"fork":false,"pushed_at":"2019-02-07T08:02:47.000Z","size":232,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T14:08:25.715Z","etag":null,"topics":["avplayer","id3","id3-parser","id3-reader","medialibrary","mpmediaplayer","music","music-library","musiclib","swift","swift4"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpongeBobSun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-07T04:47:44.000Z","updated_at":"2021-07-12T05:00:49.000Z","dependencies_parsed_at":"2022-08-20T20:50:38.116Z","dependency_job_id":null,"html_url":"https://github.com/SpongeBobSun/Holophonor","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpongeBobSun%2FHolophonor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpongeBobSun%2FHolophonor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpongeBobSun%2FHolophonor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpongeBobSun%2FHolophonor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpongeBobSun","download_url":"https://codeload.github.com/SpongeBobSun/Holophonor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724631,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avplayer","id3","id3-parser","id3-reader","medialibrary","mpmediaplayer","music","music-library","musiclib","swift","swift4"],"created_at":"2024-09-30T16:50:41.081Z","updated_at":"2025-04-13T14:08:29.634Z","avatar_url":"https://github.com/SpongeBobSun.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holophonor\n\n[![CI Status](http://img.shields.io/travis/SpongeBobSun/Holophonor.svg?style=flat)](https://travis-ci.org/SpongeBobSun/Holophonor)\n[![Version](https://img.shields.io/cocoapods/v/Holophonor.svg?style=flat)](http://cocoapods.org/pods/Holophonor)\n[![License](https://img.shields.io/cocoapods/l/Holophonor.svg?style=flat)](http://cocoapods.org/pods/Holophonor)\n[![Platform](https://img.shields.io/cocoapods/p/Holophonor.svg?style=flat)](http://cocoapods.org/pods/Holophonor)\n\n\n\n![logo](./imgs/logo.jpg)\n\nConvenience library for managing \u0026 querying music. Written in Swift.\n\n## Features\n\n* Support music file from `iTunes` library or local file \u0026 folder.\n* Parse ID3 \u0026 `iTunes` format tag information, including -\n    * artist name\n    * album name\n    * genre name\n    * artwork image, aka. cover image\n    * duration\n    * title\n    * track number\n    * file url\n* Query library by name, artist, album \u0026 several other dimensions.\n* Persistence store using `CoreData`.\n\n## Design\n### Dependencies\n\nHolophonor use `CoreData` as persistence store and use `RxSwift` as databus.\n\n### Concepts\n#### MediaItem\n\nA `MediaItem` stands for a media item as its name indicates. \n\nA media item can be a song or a representative item which can represent for an album, an artist or a genre.\n\n`MediaItem` will hold meta data of a song or represented media collection.\n\n`MediaItem` works like `MPMediaItem` in iOS's `MediaPlayer` framework.\n\n#### MediaCollection\n\nA `MediaCollection` is a collection of `MediaItem`. \n\nA `MediaCollection` contains a representative item which contains meta data of this collection.\n\n`MediaCollection` works like `MPMediaItemCollection` in iOS's `MediaPlayer` framework.\n#### Representative Item\n\nRepresentative item is an instance of `MediaItem`, which contains common meta data of a media collection.\n\nRepresentative item works like `MPMediaItemCollection.representativeItem` in iOS's `MediaPlayer` framework.\n#### Meta data\n\nID3 or iTunes format meta data in music file, which usually contains information like artist name, album name, genre name, track duration \u0026 etc.\n\nMeta data can be accessed via `MediaItem` instance.\n\nComplete fields of meta data is listed below.\n\n* albumTitle: Album's title.\n* artist: Album's artist.\n* fileURL: File's URL.\n* filePath: File's absolute path, only applied for local item.\n* genre: Genre name.\n* mediaType: Media item location - iTunes or local file.\n* trackNumber: Track number.\n* title: Title for this media item.\n* duration: Duration for this media item.\n* _itemArtwork: Artwork image for this item. Accessed via `getArtworkWithSize`\n* persistentID: Persistent id for this media item\n* albumPersistentID: Persistent id for album in database. \n* genrePersistentID: Persistent id for genre in database. \n* artistPersistentID: Persistent id for artist in database.\n* mpPersistentID: `MediaPlayer` persistent id, only applied for iTunes item.\n\n### Structures \u0026 Relationships\n\n\n## Installation\n\nHolophonor is available through [CocoaPods](http://cocoapods.org). To install\nit, simply add the following line to your Podfile:\n\n```ruby\npod \"Holophonor\"\n```\n\n## API\n\n### Initialization\n\nUse `Holophonor.instance` to initialize Holophonor and get an instance.\n\nDuring initialization, Holophonor will save its database file in -\n\n* `Documents` folder for debug build, you can dump the `sqlite` file via `iTunes`.\n* `Library` folder for non-debug build.\n\n### Local Directories\n\nHolophonor will search music in local directories and automatically add `Documents` folder to its scan path during initialization.\n\nTo add or remove a local directory from scan path, use below functions **before** rescan the library.\n\n```swift\naddLocalDirectory(dir: String)\nremoveLocalDirectory(dir: String)\n```\n\n\"dir\" is the absolute path string of a directory. Also make sure you have access permission for directories you add.\n\n### Rescan Library\n\nYou need to perform a rescan action to full fill Holophonor's database.\n\n**A rescan action will drop Holophonor's database** first and search for music files from `iTunes` and local directories.\n\nCall `rescan` function to rescan library.\n\n```swift\nrescan(_ force: Bool = false, completion: @escaping () -\u003e Void)\n```\n\nYou can observe the rescan progress by subscribe the progress subject.\n\n```swift\nobserveProgress() -\u003e PublishSubject\u003cInt64\u003e \n```\n\nAlso you can get a notification when recan started.\n\n```swift\nobserveRescan() -\u003e PublishSubject\u003cBool\u003e\n```\n\n### Queries\n\nUse query method like `holophonor.get**By(**: )` to query media items.\n\n## Example\n\n### Get all artist in library\n\n```swift\nlet foo = self.holo.getAllArtists()\nfoo.forEach({ (each) in\n    print((each.representativeItem?.artist)!)\n})\n```\n\n\n### Get all albums in library\n```swift\nlet foo = self.holo.getAllAlbums()\nfoo.forEach({ (item) in\n    print(item.representativeItem?.albumTitle)\n})\n```\n\n### Get albums by artist\n\n```swift\nlet albums = self.holo.getAlbumsBy(artist: \"The Killers\")\nlet foo = self.holo.getAllArtists()\nlet bar = self.holo.getAlbumsBy(artistId: foo.first?.artistPersistentID)\n```\n\n### Get songs in album\n```swift\nlet songs = self.holo.getAlbumsBy(artist: \"Iron Maiden\")?.first.items ?? []\nprint(songs)\n```\n\n### Get meta data in song\n```swift\nlet songs = self.holo.getAlbumsBy(artist: \"Iron Maiden\")?.first.items ?? []\nsongs.forEach({ (each) in\n    print(each.title)\n    print(each.artist)\n    print(each.albumTitle)\n    print(each.getArtworkWithSize(size: CGSize(width: 200, height: 200)) ?? #imageLiteral(resourceName: \"ic_album\"))\n    print(each.fileURL)\n    print(each.genre)\n    print(each.duration)\n    print(each.trackNumber)\n})\n```\n\nTo run the example project:\n* clone the repo\n* run `bundle install \u0026\u0026 bundle exec pod install` from the Example directory\n* open `Holophonor.xcworkspace`\n* hit the run button\n\n## APPs using this library\n\n* [Prodigal Music Player](https://github.com/SpongeBobSun/Prodigal-iOS)\n\n## About the name\n\nFrom [Futurama Wiki](https://futurama.fandom.com/wiki/Holophonor)\n\n*The Holophonor is a musical instrument of the 30th Century, it is best described as a combination of an Oboe and a Holographic Projector.*\n\n*...*\n\n*According to the commentary for Parasites Lost, the holophoner is based on the Visi-Sonor from Isaac Asimov's Foundation Trilogy published in 1951 to 1953. A similiar idea, the Sensory Syrinx, was created by Samuel R. Delany for his novel 'Nova' published in 1968.*\n\n\n## Author\n\nsponegbobsun, bobsun@outlook.com\n\n## License\n\nHolophonor is available under the MIT license. See the LICENSE file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspongebobsun%2Fholophonor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspongebobsun%2Fholophonor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspongebobsun%2Fholophonor/lists"}