diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..ce144bf1f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +# Code of Conduct + +This project follows the ownCloud Code of Conduct. + +Please read the full Code of Conduct at: +**** + +By participating in this project, you agree to abide by its terms. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cba8d8766..65c99156d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,9 @@ -## Submitting issues +# Contributing -If you have questions about how to install or use ownCloud, please direct these to the [mailing list][mailinglist] or our [forum][forum]. We are also available on [IRC][irc]. +Thank you for your interest in contributing to this project! -### Short version +Please read the full contributing guidelines at: +**** - * The [**issue template can be found here**][template]. Please always use the issue template when reporting issues. - -### Guidelines -* Please search the existing issues first, it's likely that your issue was already reported or even fixed. - - Go to one of the repositories, click "issues" and type any word in the top search/command bar. - - You can also filter by appending e. g. "state:open" to the search string. - - More info on [search syntax within github](https://help.github.com/articles/searching-issues) -* This repository ([music](https://github.com/owncloud/music/issues)) is *only* for issues within the ownCloud music code. -* __SECURITY__: Report any potential security bug to security@owncloud.com following our [security policy](https://owncloud.org/security/) instead of filing an issue in our bug tracker -* Report the issue using our [template][template], it includes all the information we need to track down the issue. - -Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues. - -[template]: https://github.com/owncloud/core/blob/master/.github/ISSUE_TEMPLATE/issue_template.md -[mailinglist]: https://mailman.owncloud.org/mailman/listinfo/owncloud -[forum]: https://forum.owncloud.org/ -[irc]: https://webchat.freenode.net/?channels=owncloud&uio=d4 - -### Contribute Code and translations -Please check [core's contribution guidelines](https://github.com/owncloud/core/blob/master/CONTRIBUTING.md) for further information about contributing code and translations. +For development setup, coding standards, and pull request process, +see the README in this repository. diff --git a/README.md b/README.md index 152df4e8b..79453ec56 100644 --- a/README.md +++ b/README.md @@ -1,345 +1,120 @@ -# README +# Music -**As of January 2026, the Nextcloud version of the Music app is hosted at https://github.com/nc-music/music. At the same time, the ownCloud version has entered maintenance mode: only bug and security fixes may still be released but no new features. All open issues are being transferred to the new repository.** + -[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/owncloud/music/badges/quality-score.png?s=ddb9090619b6bcf0bf381e87011322dd2514c884)](https://scrutinizer-ci.com/g/owncloud/music/) -[![PHP Analysis](/../../actions/workflows/php-analysis.yml/badge.svg)](/../../actions/workflows/php-analysis.yml) -[![PHP Integration Tests](/../../actions/workflows/php-integration-tests.yml/badge.svg)](/../../actions/workflows/php-integration-tests.yml) +[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](COPYING) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) [![Docker Hub](https://img.shields.io/docker/pulls/owncloud)](https://hub.docker.com/r/owncloud/server) -logotype +A full-featured music player and streaming server app for ownCloud. It scans audio files stored in your cloud, organizes them by artist and album, and provides playback through a web interface with support for MP3, FLAC, OGG/Vorbis, Opus, WAV, AAC, ALAC, and more. It also serves as an Ampache- and Subsonic-compatible streaming backend for external music players. -## Overview +## Getting Started -Music player and server for ownCloud and Nextcloud. Shows audio files stored in your cloud categorized by artists and albums. Supports mp3, and depending on the browser, many other audio formats too. Supports shuffle play and playlists. The Music app also allows serving audio files from your cloud to external applications which are compatible either with Ampache or Subsonic. +Follow the steps below to install and enable the Music app. -The full-screen albums view: -![library view](https://user-images.githubusercontent.com/8565946/132128608-34dc576b-07b7-424c-ae81-a63b9128f3d7.png) - -Music player embedded into the files view: -![files view](https://user-images.githubusercontent.com/8565946/132128626-712bf745-691e-4f03-83d7-20cbc4dd37d1.png) - -Integration with the media control panel in Chrome: -Chrome media control panel - -Mobile layout and media control integration to the lock screen and notification center with Chrome on Android: -Mobile layout Android lock screen Android notification center - -## Supported formats - -* MP3 (`audio/mpeg`) -* FLAC (`audio/flac`) -* Vorbis in OGG container (`audio/ogg`) -* Opus in OGG container (`audio/ogg` or `audio/opus`) -* WAV (`audio/wav`) -* AAC in M4A container (`audio/mp4`) -* ALAC in M4A container (`audio/mp4`) -* M4B (`audio/m4b`) -* AAC (`audio/aac`) -* AIFF (`audio/aiff`) -* AU (`audio/basic`) -* CAF (`audio/x-caf`) - -_Note: The audio formats supported vary depending on the browser. Most recent versions of Chrome, Firefox and Edge should be able to play all the formats listed above. All browsers should be able to play at least the MP3 files._ - -### Detail - -The modern web browsers ship with a wide variety of built-in audio codecs which can be used directly via the standard HTML5 audio API. Still, there is no browser which could natively play all the formats listed above. For those formats not supported natively, the Music app utilizes the Aurora.js javascript library which is able to play most of the formats listed above, excluding only the OGG containers. On the other hand, Aurora.js may not be able to play all the individual files of the supported formats and is very limited in features (no seeking, no adjusting of playback speed). - -_Note: In order to be playable in the Music app, the file type has to be mapped to a MIME type `audio/*` on your cloud instance. Neither ownCloud nor Nextcloud has these mappings by default for the file types AIFF, AU, or CAF. The mapping for the file type AAC is missing from ownCloud but present on Nextcloud. To add the missing mappings, run:_ - - php occ music:register-mime-types - -## Usage hints - -Normally, the Music app detects any new audio files in the filesystem on application start and scans metadata from those to its database tables when the user clicks the prompt. The Music app also detects file removals and modifications on the background and makes the required database changes automatically. - -If the database would somehow get corrupted, the user can force it to be rebuilt from scratch by opening the Settings (at the bottom of the left pane) and clicking the option "Reset music collection". - -### Commands - -If preferred, it is also possible to use the command line tool for the database maintenance, see https://github.com/owncloud/music/wiki/Commands. This may be quicker than scanning via the web UI in case of large music library, and optionally allows targeting more than one user at once, as well as some more options not available on the web interface. - - -### Ampache and Subsonic - -The URL you need to connect with an Ampache-compatible player is listed in the settings and looks like this: - -``` -https://cloud.domain.org/index.php/apps/music/ampache -``` - -This is the common path. Most clients append the last part (`/server/xml.server.php`) automatically. If you have connection problems, try the longer version of the URL with the `/server/xml.server.php` appended. - -Similarly, the URL used to connect with a Subsonic-compatible player is listed in the settings and looks like this: - -``` -https://cloud.domain.org/index.php/apps/music/subsonic -``` - - -#### Authentication - -Ampache and Subsonic don't use your ownCloud password for authentication. Instead, you need to use a specifically generated APIKEY with them. -The APIKEY is generated through the Music app settings accessible from the link at the bottom of the left pane within the app. The generated APIKEY is shown upon creation but it is impossible to retrieve it at later time. If you forget or misplace the key, you can always delete it and generate a new one. - -When you create the APIKEY, the application shows also the username you should use on your Ampache/Subsonic client. Typically, this is your ownCloud login name but it may also be an UUID in case you have set up LDAP authentication. +### Prerequisites +- ownCloud Server 10.x +- PHP 7.4+ ### Installation -The Music app can be installed using the App Management available on the web UI of ownCloud or Nextcloud for the admin user. - -After installation, you may want to select a specific sub-folder containing your music files through the settings of the application. This can be useful to prevent unwanted audio files to be included in the music library. - -### Known issues - -#### Huge music collections - -The application's scalability for large music collections has gradually improved as new versions have been released. Still, if the collection is large enough, the application may fail to load. The maximum number of tracks supported depends on your server but should be more than 50'000. Also, when there are tens of thousands of tracks, you may notice slow down of the web UI. - -#### Translations - -There exist partial translations for the Music app for many languages, but most of them are very much incomplete. In the past, the application was translated at https://www.transifex.com/owncloud-org/owncloud/ and the resource still exists there. However, large majority of the strings used in the app have not been picked by Transifex for many years now, and hence the translations from Transifex cannot be actually used. The root cause is disparity in the localization mechanisms used in the Music app and on ownCloud in general, and bridging the gap would require some support from ownCloud core team. This is probably never going to happen, see https://central.owncloud.org/t/owncloud-music-app-translations/14881. For now, you may contribute translations as normal pull requests, by following the instructions from https://github.com/owncloud/music/issues/671#issuecomment-782746463. - -#### SMB storage - -The Music app may be unable to extract metadata of the files residing on a SMB share. This is because, on some system configurations, it is not possible to use `fseek()` function to seek within the remote files on the SMB share. The `getID3` library used for metadata extraction depends on `fseek()` and will fail on such systems. If the metadata extraction fails, the Music app falls back to deducing the track name from the file name, album name from the parent folder name, and artist name from the grand parent folder name. Whether or not the problem exists on a system, may depend on the details of the SMB support library on the host computer and the remote computer providing the share. According to the [documentation](https://docs.nextcloud.com/server/stable/admin_manual/configuration_files/external_storage/smb.html), using the SMB storage requires either `smbclient` or `libsmbclient-php` and the latter is preferred. Installing the `libsmbclient-php` has solved this metadata issue for some users. - -## Development - -### Build frontend bundle +Install from the [ownCloud Marketplace](https://marketplace.owncloud.com) or clone into your `apps/` directory: -All the frontend javascript sources of the Music app, including the used vendor libraries, are bundled into a few files for deployment using webpack. These bundle files are named like `dist/webpack.*.js`. Similarly, all the style files of the Music app are bundled into files like `dist/webpack.*.css`. Downloading the vendor libraries and generating these bundles requires the `npm` utility, and happens by running: - - npm install --deps - npm run build - -The command above builds the minified production version of the bundle. To build the development version, use - - npm run build-dev - -To automatically regenerate the development mode bundles whenever the source .js/.css files change, use - - npm run watch - -### Build delivery package - -To build the release zip package, run the following commands. This requires the `make` and `zip` command line utilities. - - cd build - make release - -### Install test dependencies - -To install test dependencies, run the following command on the root level of the project: - - composer install - -### Run tests - -#### Static analysis with PHPStan - - composer run analyze - -#### PHP unit tests - - composer run unit-tests - -#### PHP integration tests -The integration tests require the music app to be installed under the `apps` folder of an ownCloud or Nextcloud installation. The following steps assume that the cloud installation in question has not been taken into use yet, e.g. it's a fresh clone from github. - - cd ../.. # owncloud/nextcloud core - php occ maintenance:install --admin-user admin --admin-pass admin --database sqlite - php occ app:enable music - cd apps/music - composer run integration-tests - -#### Behat acceptance tests - - cd tests - cp behat.yml.dist behat.yml - # add cloud URL and credentials for Ampache and Subsonic APIs to behat.yml - ../vendor/bin/behat - -For the acceptance tests, you need to upload all the tracks from the following zip file to your cloud instance: https://github.com/paulijar/music/files/2364060/testcontent.zip - -### Translation scripts - -The translatable strings are extracted from the front-end files of the Music app proper using the `angular-gettext` module. This is installed among other dependencies with `npm`. +```bash +git clone https://github.com/owncloud/music.git apps/music +occ app:enable music +``` -In addition, there are some translatable strings within the back-end code and in the front-end files for the embedded Files player and for the Nextcloud Dashboard widget. These are handled using the perl script `l10n/l10n.pl`. In addition to the perl interpreter, this script requires the module `Locale::PO` (can be installed with CPAN) and the `xgettext` tool. On Linux, the latter should be available with `apt-get install gettext` or similar. On Windows, this needs to be installed manually and the executable must be added to the PATH; at least the version 0.22.5 from https://github.com/vslavik/gettext-tools-windows/releases seems to work well. +### Supported Formats -When the tools are setup correctly, all the strings can be extracted from the source codes to `l10n/templates/music.pot` with the command: +MP3, FLAC, Vorbis (OGG), Opus (OGG), WAV, AAC (M4A), ALAC (M4A), M4B, AIFF, AU, CAF - cd build - make l10n-extract +## Documentation -The music.pot file can then be used to update the language-specific translation file (l10n/*/music.po) as described in https://github.com/owncloud/music/issues/671#issuecomment-782746463. +- [ownCloud Server Admin Manual](https://doc.owncloud.com/server/latest/admin_manual/) +- [ownCloud Marketplace](https://marketplace.owncloud.com) -Once the translations have been updated in the .po files, we need to generate the final source files used to build the Music application. This, again, uses both `angular-gettext` and `l10n/l10n.pl`. For this, execute +## Part of ownCloud Server (Classic) - cd build - make l10n-clone - make l10n-compile +This app is a plugin for [ownCloud Server 10](https://github.com/owncloud/core). -The step `l10n-clone` above makes copies of some translations to different language codes. This is needed because ownCloud and Nextcloud use slightly different language codes in some cases. Furthermore, the clouds may support multiple versions of the same language but the Music app currently has identical translation for each of them. +> **Note:** As of January 2026, the Nextcloud version of the Music app has moved to [nc-music/music](https://github.com/nc-music/music). The ownCloud version is in maintenance mode -- only bug and security fixes will be released. -## API +The ownCloud Server is available on [Docker Hub](https://hub.docker.com/r/owncloud/server). -The Music app back-end implements the [Shiva API](https://shiva.readthedocs.org/en/latest/resources/base.html) except the resource `/artists//shows`. The endpoints of this API can be found under `https://own.cloud.example.org/index.php/apps/music/api/`. The Shiva API could be used by other applications running on ownCloud/Nextcloud to access the library contents. This API is accessible only with a valid cloud user session which makes it difficult to use for clients running outside of the hosting cloud. +## Community & Support -To connect external client applications, partial implementations of the following APIs are available: +**[Star](https://github.com/owncloud/music)** this repo and **Watch** for release notifications! -* [Ampache XML API](https://github.com/ampache/ampache/wiki/XML-methods) at `/ampache/server/xml.server.php` -* [Ampache JSON API](https://github.com/ampache/ampache/wiki/JSON-methods) at `/ampache/server/json.server.php` -* [Subsonic API](http://www.subsonic.org/pages/api.jsp) at `/subsonic/rest/{method}` +- [ownCloud Website](https://owncloud.com) +- [Community Discussions](https://github.com/orgs/owncloud/discussions) +- [Matrix Chat](https://app.element.io/#/room/#owncloud:matrix.org) +- [Documentation](https://doc.owncloud.com) +- [Enterprise Support](https://owncloud.com/contact-us/) +- [OSPO Home](https://kiteworks.com/opensource) -The web interface of the Music app uses a proprietary REST API. Note that this API may change between the application versions without prior notice. For list of all available endpoints, see [appinfo/routes.php](https://github.com/owncloud/music/blob/master/appinfo/routes.php). As this API is not documented anywhere, the details of each endpoint have to be checked from the implementation. See [here](https://github.com/owncloud/music/issues/1012#issuecomment-1256943457) for some hints. +## Contributing +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. -### `/api/log` +### Workflow -Allows to log a message to ownCloud defined log system. +- **Rebase Early, Rebase Often!** We use a rebase workflow. Always rebase on the target branch before submitting a PR. +- **Dependabot**: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly. +- **Signed Commits**: All commits **must** be PGP/GPG signed. See [GitHub's signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification). +- **DCO Sign-off**: Every commit must carry a `Signed-off-by` line: + ``` + git commit -s -S -m "your commit message" + ``` +- **GitHub Actions Policy**: Workflows may only use actions that are (a) owned by `owncloud`, (b) created by GitHub (`actions/*`), or (c) verified in the GitHub Marketplace. - POST /api/log +## Translations -Parameters: +Help translate this project on Transifex: +**** - { - "message": "The message to log" - } +Please submit translations via Transifex -- do not open pull requests for translation changes. -Response: +## Security - { - "success": true - } +**Do not open a public GitHub issue for security vulnerabilities.** +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). -### `/api/collection` +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) -Returns all artists with nested albums and each album with nested tracks. Each track carries a file ID which can be used to obtain the file path with `/api/file/{fileId}/path`. The front-end converts the path into playable WebDAV link like this: `OC.linkToRemoteBase('webdav') + path`. +## License - GET /api/collection +This project is licensed under the [AGPL-3.0](COPYING). -Response: +## About the ownCloud OSPO - [ - { - "id": 2, - "name": "Blind Guardian", - "albums": [ - { - "name": "Nightfall in Middle-Earth", - "year": 1998, - "disk" : 1, - "cover": "/index.php/apps/music/api/album/16/cover", - "id": 16, - "tracks": [ - { - "title": "A Dark Passage", - "number": 21, - "artistId": 2, - "files": { - "audio/mpeg": 1001 - }, - "id": 202 - }, - { - "title": "Battle of Sudden Flame", - "number": 12, - "artistId": 2, - "files": { - "audio/mpeg": 1002 - }, - "id": 212 - } - ] - } - ] - }, - { - "id": 3, - "name": "blink-182", - "albums": [ - { - "name": "Stay Together for the Kids", - "year": 2002, - "disk" : 1, - "cover": "/index.php/apps/music/api/album/22/cover", - "id": 22, - "tracks": [ - { - "title": "Stay Together for the Kids", - "number": 1, - "artistId": 3, - "files": { - "audio/ogg": 1051 - }, - "id": 243 - }, - { - "title": "The Rock Show (live)", - "number": 2, - "artistId": 3, - "files": { - "audio/ogg": 1052 - }, - "id": 244 - } - ] - } - ] - } - ] - -### Creating APIKEY for Subsonic/Ampache - -The endpoint `/api/settings/userkey/generate` may be used to programmatically generate a random password to be used with an Ampache or a Subsonic client. The endpoint expects two parameters, `length` and `description` (both optional) and returns a JSON response. -Please note that the minimum password length is 10 characters. The HTTP return codes represent also the status of the request. +The [Kiteworks Open Source Program Office](https://kiteworks.com/opensource), operating under +the [ownCloud](https://owncloud.com) brand, launched on May 5, 2026, to steward the open source +ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance, +community health, and sustainable collaboration between the open source community and +[Kiteworks](https://www.kiteworks.com), which acquired ownCloud in 2023. -``` -POST /api/settings/userkey/generate -``` +- **OSPO Home**: +- **GitHub**: +- **ownCloud**: -Parameters: +For questions about the OSPO or licensing, contact ospo@kiteworks.com. -``` -{ - "length": , - "description": -} -``` +### License Migration to Apache 2.0 -Response (success): +The OSPO is driving a strategic relicensing of ownCloud repositories toward the +[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0), following +the [Apache Software Foundation's third-party license policy](https://www.apache.org/legal/resolved.html). -``` -HTTP/1.1 201 Created +Individual repositories will migrate as their audit is completed. The LICENSE file +in each repo reflects its **current** license status (not the target). -{ - "id": , - "password": , - "description": -} -``` +**Current license: AGPL-3.0** (Category X per Apache policy -- cannot be included in Apache-2.0 works). -Response (error - no description provided): - -``` -HTTP/1.1 400 Bad request - -{ - "message": "Please provide a description" -} -``` - -Response (error - error while saving password): - -``` -HTTP/1.1 500 Internal Server Error - -{ - "message": "Error while saving the credentials" -} -``` +Migration prerequisites for this repository: +- **CLA/DCO coverage**: All past contributors must have signed agreements permitting relicensing +- **Copyleft dependency audit**: All AGPL/GPL dependencies must be replaced or isolated +- **KDE heritage review**: Any code with KDE-era copyrights requires legal analysis +- **Complete relicensing**: AGPL-3.0 is a strong copyleft license; migration requires full relicensing of all files, not just a header change diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..78094ae4c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a Vulnerability + +**Do NOT open a public GitHub issue for security vulnerabilities.** + +Please report security issues responsibly via: +**** + +You can also report vulnerabilities through our YesWeHack bug bounty program: +**** diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 000000000..d87c0ca86 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +For support with this project, please use the following channels: + +- **Enterprise Support**: +- **Community discussions**: https://github.com/orgs/owncloud/discussions +- **Matrix Chat**: +- **Documentation**: + +Please do not use GitHub issues for general support questions. diff --git a/agents.md b/agents.md new file mode 100644 index 000000000..8dafdbaa3 --- /dev/null +++ b/agents.md @@ -0,0 +1,66 @@ +# agents.md -- Music + +## Repository Overview + +Full-featured music player and streaming server app for ownCloud. Licensed under AGPL-3.0. PHP backend with JavaScript frontend. The ownCloud version is in maintenance mode (bug/security fixes only). + +## Architecture & Key Paths + +- `lib/` -- PHP application logic +- `js/` -- Frontend JavaScript +- `css/` -- Stylesheets +- `templates/` -- Server-side templates +- `appinfo/` -- ownCloud app metadata +- `l10n/` -- Translation files +- `3rdparty/` -- Bundled third-party libraries +- `tests/` -- Unit tests +- `img/` -- Images and logos +- `build/` -- Build scripts +- `Makefile` -- (not present, uses npm scripts) +- `composer.json` -- PHP dependencies +- `package.json` -- Node.js dependencies +- `webpack.config.js` -- Webpack configuration + +## Development Conventions + +- PHP backend follows ownCloud coding standards +- JavaScript frontend built with webpack +- Static analysis with PHPStan +- Scrutinizer CI for code quality + +## Build & Test Commands + +```bash +npm install # Install Node.js dependencies +composer install # Install PHP dependencies +# Build and test through ownCloud app framework +``` + +## Important Constraints + +- Licensed under AGPL-3.0 (copyleft). Apache 2.0 migration planned. +- In maintenance mode -- only bug and security fixes. +- All contributions require a DCO sign-off. + + +## OSPO Policy Constraints + +### GitHub Actions +- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers. +- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@ # vX.Y.Z` +- Never introduce actions from unverified third parties. + +### Dependency Management +- Dependabot is configured for automated dependency updates. +- Review and merge Dependabot PRs as part of regular maintenance. +- Do not introduce new dependencies without discussion in an issue first. + +### Git Workflow +- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing. +- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`). +- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`). +- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this. + +## Context for AI Agents + +This is a classic OC10 app with Ampache and Subsonic API compatibility. The app scans audio files in user storage and provides web-based playback. The Nextcloud version has moved to a separate repository. Changes should be limited to bug/security fixes.