fcode
/
delarte
3
2
Fork 1
Code Issues 1 Pull Requests 1 Projects 1 Releases Activity

Terminology and harmful language consideration #12

New Issue
Closed
opened 2022-12-12 07:30:49 +00:00 by Barbagus · 5 comments
Barbagus commented 2022-12-12 07:30:49 +00:00
Collaborator
Copy Link

The protocol used by the service is called HLS. There is a defined terminology in this standard and it would make sens to use it in the code.

For instance:

  • our chunks or ranges are called fragment
  • our resolutions are called variants
  • etc..
The protocol used by the service is called [HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming). There is a defined terminology in this standard and it would make sens to use it in the code. For instance: - our `chunks` or `ranges` are called `fragment` - our `resolutions` are called `variants` - etc..
Barbagus added reference stable 2022-12-12 12:13:21 +00:00
Barbagus commented 2022-12-13 08:44:51 +00:00
Author
Collaborator
Copy Link

After further look in the actual RFC for HLS protocol, it turns out that, among other changes:

  • versions are actually renditions
  • resolutions are actually variants

Althought it makes sens to adopt actual terms in the code (see, #15), in terms of user interface (arument names, usage string, prompts, etc...) I can see it be rather confusing.

Opinions ?

After further look in the actual [RFC](https://datatracker.ietf.org/doc/html/rfc8216#page-6) for HLS protocol, it turns out that, among other changes: - _versions_ are actually _renditions_ - _resolutions_ are actually _variants_ Althought it makes sens to adopt actual terms in the code (see, #15), in terms of user interface (arument names, usage string, prompts, etc...) I can see it be rather confusing. Opinions ?
Barbagus added a new dependency 2022-12-13 16:28:30 +00:00
#11 Custom renditions
Barbagus removed a dependency 2022-12-13 16:28:38 +00:00
#11 Custom renditions
remace07 commented 2022-12-14 05:15:33 +00:00
Collaborator
Copy Link

To me, in user interface, the most understandable should be used, so... "versions" and "resolutions" should be displayed, as A lambda user shouldn't have to search for Arte's API doc or RFC for using your script.

in the code, using different vocabulary for the same thing might be a bad idea, as You already said that.

so I think, if this information is needed somewhere user-wise, Arte's API names or RFC names should appear only in help strings. else, it should appear nowhere.

a help string could be:

delarte --help
[...]
resolution: string representing the resolution of the video. refers to "variant" in RFC8216
example: "1080p"

To me, in user interface, the most understandable should be used, so... "versions" and "resolutions" should be displayed, as A lambda user shouldn't have to search for Arte's API doc or RFC for using your script. in the code, using different vocabulary for the same thing might be a bad idea, as You already said that. so I think, if this information is needed somewhere user-wise, Arte's API names or RFC names should appear only in help strings. else, it should appear nowhere. a help string could be: > delarte --help >[...] > resolution: string representing the resolution of the video. refers to "variant" in [RFC8216](https://datatracker.ietf.org/doc/html/rfc8216#page-5) > example: "1080p"
👍 1
Barbagus commented 2022-12-14 08:17:57 +00:00
Author
Collaborator
Copy Link

so I think, if this information is needed somewhere user-wise, Arte's API names or RFC names should appear only in help strings. else, it should appear nowhere.

Maybe not even in help string :)

> so I think, if this information is needed somewhere user-wise, Arte's API names or RFC names should appear only in help strings. else, it should appear nowhere. Maybe not even in help string :)
Barbagus commented 2022-12-20 09:00:06 +00:00
Author
Collaborator
Copy Link

I share the idea of not exposing HLS specific terminology (rendition, variants) to the user. But I have to say that the term version is making me nervous as it carries already a lot of meaning in the context of a computer programs, usually the version of the program itself (very common -v or --version).

I am not saying this is a problem, however if someone thinks about an alternative for version I belive it would be worth considering.

I share the idea of not exposing HLS specific terminology (rendition, variants) to the user. But I have to say that the term `version` is making me nervous as it carries already a lot of meaning in the context of a computer programs, usually the version of the program itself (very common `-v` or `--version`). I am not saying this is a problem, however if someone thinks about an alternative for `version` I belive it would be worth considering.
Barbagus changed title from Fix terminology to Terminology and harmful language consideration 2022-12-30 08:21:03 +00:00
Barbagus commented 2022-12-30 08:28:48 +00:00
Author
Collaborator
Copy Link

The HTTP Live Streaming RFC make extensive use of the master playlist term. To avoid confusion, it was easier to just use the same words in our code.

On the other hand I must admit, that master playlist and media playlist never quite made sense to me, ever. Especially because they are not lists of things to be played in sequence.

At the risk of introducing some confusion by using different term than in the standard, I would consider using ProgramIndex (instead of master playlist) and TrackIndex (instead of media playlist)

I realize that index is sort of a catch-all word, plus its plural form just calls for trouble (indexes vs. indices). So any other suggestion is welcome !

The [HTTP Live Streaming](https://www.rfc-editor.org/rfc/rfc8216) RFC make extensive use of the _master playlist_ term. To avoid confusion, it was easier to just use the same words in our code. On the other hand I must admit, that _master playlist_ and _media playlist_ never quite made sense to me, ever. Especially because they are not _lists_ of things to be played _in sequence_. At the risk of introducing some confusion by using different term than in the standard, I would consider using `ProgramIndex` (instead of _master playlist_) and `TrackIndex` (instead of _media playlist_) I realize that _index_ is sort of a catch-all word, plus its plural form just calls for trouble (_indexes_ vs. _indices_). So any other suggestion is welcome !
Sign in to join this conversation.
stable
Branches Tags
Clear current reference
stable
model
devel
draft
Clear current reference
Labels
Clear labels   
bug

Something is not working

  
duplicate

This issue or pull request already exists

  
enhancement

New feature

  
help wanted

Need some help

  
invalid

Something is wrong

  
question

More information is needed

  
wontfix

This won't be fixed

No Label
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: fcode/delarte#12
No description provided.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?