| Name | mkdocs-wavesurfer JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | MkDocs plugin for wavesurfer.js |
| upload_time | 2025-07-14 18:02:53 |
| maintainer | None |
| docs_url | None |
| author | Anders Eskildsen |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mkdocs-wavesurfer
This is a plugin for [mkdocs](https://www.mkdocs.org/) that adds a waveform display for `<audio>` elements using [wavesurfer.js](https://wavesurfer.xyz/).
This plugin only works when [mkdocs-audiotag](https://github.com/aeskildsen/mkdocs-audiotag) is also installed and enabled.
## Quick start
### Install the plugin
```shell
pip install mkdocs-wavesurfer
```
### Enable the plugin in mkdocs.yml
```yaml
plugins:
- mkdocs-audiotag # required
- mkdocs-wavesurfer
```
### Embed an audio file in markdown source
As described on the [mkdocs-audiotag readme](https://github.com/aeskildsen/mkdocs-audiotag).
```markdown
```
The waveform will be shown below the audio element's controls.
## Configuration
You can tweak how *wavesurfer.js* displays the waveform using a range of configuration options. See the [wavesurfer.js documentation](https://wavesurfer.xyz/docs/types/wavesurfer.WaveSurferOptions) and the very nice [visual examples](https://wavesurfer.xyz/examples/?all-options.js) for a full description.
Add your options under the `mkdocs-wavesurfer` plugin in your `mkdocs.yml`.
```yaml
plugins:
- mkdocs-audiotag
- mkdocs-wavesurfer:
height: 200
wave_color: "#0fcb2bff"
progress_color: rgb(0, 100, 0)
cursor_color: red
cursor_width: 10
bar_width: 5
bar_gap: 2
```
Note:
- **Defaults:** You only need to specify the options you want to override, as others will use default values.
- **Colors:** Can be specified as in CSS using hex values, rgb(), or color names, as shown in the example above.
- **Case:** We use snake case in `mkdocs.yml` for consistency, as opposed to the wavesurfer.js docs which use javascript and camel case.
### Use with mkdocs-material
The plugin can adapt to the color set by [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for a visually coherent style.
```yaml
plugins:
- mkdocs-audiotag
- mkdocs-wavesurfer:
use_mkdocs-material_color: true
```
When this is enabled, the options `wave_color` and `progress_color` are overwritten, and the plugin will log a warning if they are present in `mkdocs.yml`.
### Autopopulated options
Please note that the following wavesurfer options are populated automatically by the plugin and cannot be specified in the config:
- `media_controls`
- `media`
- `url`
- `container`
If you would like to remove the browser's default media controls, you can do so by configuring [mkdocs-audiotag](https://github.com/aeskildsen/mkdocs-audiotag):
```yaml
plugins:
- mkdocs-audiotag:
controls: false
- mkdocs-wavesurfer
```
### Default config values
Below are the default configuration values:
```yaml
plugins:
- mkdocs-wavesurfer:
height: 128
width: "100%"
split_channels: false
normalize: false
wave_color: "#ff4e00"
progress_color: "#dd5e98"
cursor_color: "#ddd5e9"
cursor_width: 2
bar_width: null
bar_gap: null
bar_radius: null
bar_height: null
bar_align: ""
min_px_per_sec: 1
fill_parent: true
autoplay: false
interact: true
drag_to_seek: false
hide_scrollbar: false
audio_rate: 1.0
auto_scroll: true
auto_center: true
sample_rate: 8000
use_mkdocs_material_color: false
```
## License
This plugin is licensed under the MIT license.
Beware that [wavesurfer.js is licensed under the BSD-3-Clause license](https://github.com/katspaugh/wavesurfer.js?tab=BSD-3-Clause-1-ov-file).
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-wavesurfer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Anders Eskildsen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/51/81/ce3d6907cf69d42830f71023108699644724479ede449cfaafcc0ec89be4/mkdocs_wavesurfer-0.1.1.tar.gz",
"platform": null,
"description": "# mkdocs-wavesurfer\n\nThis is a plugin for [mkdocs](https://www.mkdocs.org/) that adds a waveform display for `<audio>` elements using [wavesurfer.js](https://wavesurfer.xyz/).\n\nThis plugin only works when [mkdocs-audiotag](https://github.com/aeskildsen/mkdocs-audiotag) is also installed and enabled.\n\n## Quick start\n\n### Install the plugin\n\n```shell\npip install mkdocs-wavesurfer\n```\n\n### Enable the plugin in mkdocs.yml\n\n```yaml\nplugins:\n - mkdocs-audiotag # required\n - mkdocs-wavesurfer\n```\n\n### Embed an audio file in markdown source\n\nAs described on the [mkdocs-audiotag readme](https://github.com/aeskildsen/mkdocs-audiotag).\n\n```markdown\n\n```\n\nThe waveform will be shown below the audio element's controls.\n\n## Configuration\n\nYou can tweak how *wavesurfer.js* displays the waveform using a range of configuration options. See the [wavesurfer.js documentation](https://wavesurfer.xyz/docs/types/wavesurfer.WaveSurferOptions) and the very nice [visual examples](https://wavesurfer.xyz/examples/?all-options.js) for a full description.\n\nAdd your options under the `mkdocs-wavesurfer` plugin in your `mkdocs.yml`.\n\n```yaml\nplugins:\n - mkdocs-audiotag\n - mkdocs-wavesurfer:\n height: 200\n wave_color: \"#0fcb2bff\"\n progress_color: rgb(0, 100, 0)\n cursor_color: red\n cursor_width: 10\n bar_width: 5\n bar_gap: 2\n```\n\n\n\nNote:\n\n- **Defaults:** You only need to specify the options you want to override, as others will use default values.\n- **Colors:** Can be specified as in CSS using hex values, rgb(), or color names, as shown in the example above.\n- **Case:** We use snake case in `mkdocs.yml` for consistency, as opposed to the wavesurfer.js docs which use javascript and camel case.\n\n### Use with mkdocs-material\n\nThe plugin can adapt to the color set by [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for a visually coherent style.\n\n```yaml\nplugins:\n - mkdocs-audiotag\n - mkdocs-wavesurfer:\n use_mkdocs-material_color: true\n```\n\nWhen this is enabled, the options `wave_color` and `progress_color` are overwritten, and the plugin will log a warning if they are present in `mkdocs.yml`.\n\n### Autopopulated options\n\nPlease note that the following wavesurfer options are populated automatically by the plugin and cannot be specified in the config:\n\n- `media_controls`\n- `media`\n- `url`\n- `container`\n\nIf you would like to remove the browser's default media controls, you can do so by configuring [mkdocs-audiotag](https://github.com/aeskildsen/mkdocs-audiotag):\n\n```yaml\nplugins:\n - mkdocs-audiotag:\n controls: false\n - mkdocs-wavesurfer\n```\n\n### Default config values\n\nBelow are the default configuration values:\n\n```yaml\nplugins:\n - mkdocs-wavesurfer:\n height: 128\n width: \"100%\"\n split_channels: false\n normalize: false\n wave_color: \"#ff4e00\"\n progress_color: \"#dd5e98\"\n cursor_color: \"#ddd5e9\"\n cursor_width: 2\n bar_width: null\n bar_gap: null\n bar_radius: null\n bar_height: null\n bar_align: \"\"\n min_px_per_sec: 1\n fill_parent: true\n autoplay: false\n interact: true\n drag_to_seek: false\n hide_scrollbar: false\n audio_rate: 1.0\n auto_scroll: true\n auto_center: true\n sample_rate: 8000\n use_mkdocs_material_color: false\n```\n\n## License\n\nThis plugin is licensed under the MIT license.\n\nBeware that [wavesurfer.js is licensed under the BSD-3-Clause license](https://github.com/katspaugh/wavesurfer.js?tab=BSD-3-Clause-1-ov-file).\n",
"bugtrack_url": null,
"license": null,
"summary": "MkDocs plugin for wavesurfer.js",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/aeskildsen/mkdocs-wavesurfer"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e36d24e9e2c02c4d9f32986eb3a4a3c4603b11a67dfb72fc1db9581d52484a6a",
"md5": "bdfbfc21e6d9373bc1472d621a5e014a",
"sha256": "67c77d4a97c968bd328aa4639b664fc81beafdb27eafe7717053c8fcc547ad4b"
},
"downloads": -1,
"filename": "mkdocs_wavesurfer-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bdfbfc21e6d9373bc1472d621a5e014a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6369,
"upload_time": "2025-07-14T18:02:52",
"upload_time_iso_8601": "2025-07-14T18:02:52.213402Z",
"url": "https://files.pythonhosted.org/packages/e3/6d/24e9e2c02c4d9f32986eb3a4a3c4603b11a67dfb72fc1db9581d52484a6a/mkdocs_wavesurfer-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5181ce3d6907cf69d42830f71023108699644724479ede449cfaafcc0ec89be4",
"md5": "3d38707230c99420ca68bda94ba47bb6",
"sha256": "2b9aaaeffbad8da4c66f892b2d0a4e43df310116aaace4a38191dc50152f905f"
},
"downloads": -1,
"filename": "mkdocs_wavesurfer-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3d38707230c99420ca68bda94ba47bb6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5665,
"upload_time": "2025-07-14T18:02:53",
"upload_time_iso_8601": "2025-07-14T18:02:53.270250Z",
"url": "https://files.pythonhosted.org/packages/51/81/ce3d6907cf69d42830f71023108699644724479ede449cfaafcc0ec89be4/mkdocs_wavesurfer-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 18:02:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aeskildsen",
"github_project": "mkdocs-wavesurfer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-wavesurfer"
}
