WHISPERER.md

About the project

The OBSIDIAN editor is mainly used as a zettelkasten tool, but some use it for engineering purposes (tech. documentation, wiki), and some for creative purposes: writing DND campaigns, wikis for their universes (world building), and the like.

In all cases, individually, a person will want to attach this or that musical accompaniment to a project, and in some cases to individual files, as if reflecting the atmosphere or working mood with the help of music.

The sought-after project solves this case and presents basic, but flexible functionality for solving such problems.

Built-with

Project is created and written with help of:

Getting started

Before asking questions, read this block because here is all the primary information on the project, which can answer your future not-yet asked questions.

Prerequisites

For usage of this project just as template for your repository, there is no direct prerequisites besides Node.js.

But, for contributing to this project, we highly recommending following those prerequisites:

• Installed Node.js on your desktop on which you will edit/setup this project;
• Installed Python if you want to contribute to the scripts of this project (in terms of .PY scripts);
• It is recommended to use GitHub CLI on your machine for better experience via working not only within this project, but this the .GIT in entirety;
• Installed Obsidian™, app, for which this plugin is created and on which you'll test/use this plugin;

Installation

Permission is granted for free use in any of your products.

If you want to use this project, there are two ways to download-and-use this project: "official" and direct, so, let's start from official path:

1. Go up to the "main position" of page of this repository and seek for the "Use this template" button;
2. Click on this button and seek for the specified variants "Use this template → Create a new repository", or option with codespaces;
3. Use project, edit anything you want.

Guidelines for direct-installation way:

1. Go to your vault's settings, and go to "Settings → Community plugins" and go to the second step;
2. Disable restricted mode, and use "Community plugins → Browse" to find this plugin: type the name of the project or just write "any as note";
3. Use plugin, edit vault's ambience, set music to specified files accordingly.
4. Download last tag on project's repository, for the last ZIP-tarball link provided below:
   download latest release
   • or just download the source-code through "Code → Download ZIP (or any option that you want)", and proceed to the next step;
5. Within downloaded ZIP (or project), clone everything and paste to the directory of your project via "copy+paste" procedure;
6. Now, you can use project just as if you installed it from other algorithms.

Guidelines for installation of source code of this project:

1. Clone the repository with any form of app which supports Git (or CLI of this site), guide is attached:
   https://www.howtogeek.com/451360/how-to-clone-a-github-repository/
2. Open it with any suitable for you editor and feel free to customize, update and/or contribute to this project[^1].

Usage

Usage of WHISPERER.md project is very intuitive thanks to the editor's design and predefined settings functionality, by default, vault's ambience functionality is turned on, but you need to assign which track (YouTube, SoundCloud or audio-file) you want to hear in your vault's environment.

[!Tip] Local audio files are defined by a relative path to the file itself from Vault relative path (e.g., ./folder/audio.mp4).
This applies not only to global settings but also to paths as properties, i.e., any paths are specified relative to the root directory of your Vault.

1. Go to your vault's settings and seek for "community plugins" sector, if you have restricted mode, repeat first and second steps of official installation guide¹;
2. If you have installed plugin and app saw it, you can see element named "Whisperer": open it and seek for settings, change your environment's setup according to your desires.
3. Listen to your prefered ambience in a way you want.

More about plugin's functionality and how to use it, read at the wiki:\

• Whisperer's wiki

Roadmap

• Adapt project's infrastructure (repository from template) for it's needs and requirements;
• Write first version of project;
• Publish it on OBSIDIAN's plugins registry;
• Write a wiki for the project;
• Make more advanced controls over music in the vault and files;
  • Add ability to debug iframes;
• Rewrite project to use native APIs of Youtube/Soundcloud/audio-element:
  • Youtube's API Player;
  • Soundcloud's API Player;
  • Advanced local audio player (instead of simplificated audio-tag);

Contributing

Contributions are what make open source community such an interest place to be in, so any form of contribution are greatly appreciated.

If you think that you can help this project become better but think its not so important/realizable in the current situtation or for a full contribution, use issues page, otherwise there is a guideline and policy for contributing.

If you want to contribute to this project, please, read contributioning policy and commit convention, this repository works with CLA, commits convention and on automated deployment system².

[!Important] For one-single file contributioning, use a more quicker way without forking the repository through site.

More about it in this article:

• "Working with forks" about syncing one-file fork;

License

Project thanks the Electron.js and Angular for their amazing repository scripts and entire infrastructure, which partially were imported to this repository.

[!Note] For individual licensing and credits information, seek correspondive files and/or sources.

Project itself is being distributed under the MIT License — see the file for more specified information.

Entirery of project's infrastructure is taken from repository template project:
https://github.com/Falcion/Patternugit

Contact

For any legal purposes, you can contact developer/maintainer through its email:

• Outlook email
  You can also check contact information in CODEOWNERS file within referencing our contacts.

If the developer/maintainer didn't answered, or you have other questions in nature, you can use issues page on this repository via specified templates or indirect self-written issue.

Acknowledgments

• https://shields.io/
• https://simpleicons.org/
• https://gitignore.io/
• https://gitattributes.io/
  • this generator is discontinued, use:
    https://richienb.github.io/gitattributes-generator/
• Best readme template