q/glowers-radio
1
0
Fork 0
forked from jon/glowers-radio
Code Issues Pull Requests Packages Projects Releases Wiki Activity

readme.md: reorder best practices

Browse Source
This commit is contained in:
Jon 2022-12-13 07:46:58 +00:00
parent ec6b8f6c07
commit d14fac4956
1 changed files with 23 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
readme.md
View File

@ -3,22 +3,13 @@ This repo contains backing information for Glowers Radio.
## Contributing ## Contributing
If you have a song in mind that would fit on Glowers Radio, you are free to create a PR or send in a diff for `generate.js`. If you have a song in mind that would fit on Glowers Radio, you are free to create a PR or send in a diff for `generate.js`.
The living schema is documented [below](#format) and mostly maps 1:1 to `MediaItem` The living schema is documented [below](#format) and mostly maps 1:1 to `MediaItem`, you should also check the `MediaItem` for the
the media that is most similar to what you wish to add.
## Best Practices ## Best Practices
- Use an alpha-numeric id. Don't use dashes or hyphens; Uppercase characters *may* be used when appropriate. - Use an alpha-numeric id. Don't use dashes or hyphens; Uppercase characters *may* be used when appropriate.
- Use `image/png`, `image/jpg`, `image/gif`, `audio/mp3`, and `video/mp4`. Files *should* be under 10MB and be of reasonable or tolerable quality
- Declare metadata when available. If you do not know the original source, try to find it first. - Declare metadata when available. If you do not know the original source, try to find it first.
- Metadata **must** be accurate and not an artists rendition of the actual metadata. - Metadata **must** be accurate and not an artists rendition of the actual metadata.
- Try not to use reuploads, remasters, or edits, as the source; Unless the edit or remaster is the actual media.
- Sources *should* contain codec information; if you are unsure of what correct codecs to declare, do not declare any or ask for help.
No codec declarations are better than incorrect codec declarations. See [MDN](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#basic_syntax) for details
- Don't use videos where audio alongside AlbumArt would functionally identical. Lyrics videos are ok
- All content *should* be hosted on Glowers Club. If you are not a Glower then your uris will be reuploaded if your Item(s) are accepted
- Provide fallbacks for sources and previews when possible:
- `video/` *should* have a thumbnail preview.
- `video/` *should* have a `SQUARE` fallback preview for audioOnly and for when the agent does not support the provided `video/`.
- Animated previews **must** always have a `image/gif` fallback.
- Items that aren't primarily music should be tagged with `misc`. - Items that aren't primarily music should be tagged with `misc`.
- Use the `metadata-prefer-id` tag if the actual title would be too long, cubersome, or unrelated. i.e: - Use the `metadata-prefer-id` tag if the actual title would be too long, cubersome, or unrelated. i.e:
- `slamtris`: Slamtris - Quad City DJs vs Hirokazu Tanaka *(cumbersome)* - `slamtris`: Slamtris - Quad City DJs vs Hirokazu Tanaka *(cumbersome)*
@ -30,6 +21,27 @@ The living schema is documented [below](#format) and mostly maps 1:1 to `MediaIt
- `niggatorial`: I'm The 2007 YouTube Tutorial *(cumbersome)* - `niggatorial`: I'm The 2007 YouTube Tutorial *(cumbersome)*
- `honorary`: Erika *(unrelated)* - `honorary`: Erika *(unrelated)*
<br/>
- Use `image/png`, `image/jpg`, `image/gif`, `audio/mp3`, and `video/mp4`. Files *should* be under 10MB and be of reasonable or tolerable quality
- Try not to use reuploads, remasters, or edits, as the source; Unless the edit or remaster is the actual media.
- Don't use videos where audio alongside artwork would functionally identical. Lyrics videos are ok
- Sources *should* contain codec information; if you are unsure of what correct codecs to declare, do not declare any or ask for help.
No codec declarations are better than incorrect codec declarations. See [MDN](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#basic_syntax) for details
- All content *should* be hosted on Glowers Club. If you do not Glow, then your sources will be reuploaded if your Item(s) are accepted
<br/>
- `video/` **must** have a thumbnail preview.
- `video/` *should* have a `EDisplayType.SQUARE` fallback for audioOnly, and for when the agent does not support the provided `video/`.
- Animated previews **must** always have a `image/gif` fallback.
- Avoid using `EDisplayType.LANDSCAPE` when possible.
- `EDisplayType.SQUARE` previews **must** be exactly `1:1`; `EDisplayType.LANDSCAPE` previews *should* be exactly `16:9`, or **must** be a close equivalent
## Format ## Format
The `songs.json` format **is only intended for use for Glowers Radio**, and is effectively a living standard as a result. **Live data may change drastically without warning** The `songs.json` format **is only intended for use for Glowers Radio**, and is effectively a living standard as a result. **Live data may change drastically without warning**
@ -111,11 +123,6 @@ properties:
- required: [ type, url ] - required: [ type, url ]
properties: properties:
type: { type: string, format: mimetype } type: { type: string, format: mimetype }
codecs:
description: 'A list of codec declarations. This is checked alongside the type on the client'
type: array
items:
- type: string
uri: { "$ref": "#/$defs/GWRadioURI" } uri: { "$ref": "#/$defs/GWRadioURI" }
previews: previews:
description: >- description: >-