early chapters reorganization + new Using Microphones and DJ Hardware chapters#60
Conversation
Be-ing
force-pushed
the
sound_io_rewrite
branch
from
7bc7f56 to
4f6c08a
Compare
esbrandt
left a comment
esbrandt
left a comment
There was a problem hiding this comment.
Thanks for the changes so far.
Some additional remarks while you continue:
- Please set the max column-width to 80-columns, see developer guidelines (linked in a comment above). This really helps to improve readability of the code.
- The long texts have a high information density, and could use more paragraphs.
While you added great info, and looking at the stubs there is more to come, i do think the manual should not go too deep right from the beginning and start with a comprehensive read about DJ Hardware ( see https://github.com/mixxxdj/manual/blob/manual/source/manual_guidelines.rst#what-is-the-intended-outcome-of-the-manual). This puts us at risk to loose readers pretty fast.
What are your further plans re: organizing?
If we clarify beforehand, we can work more targeted.
| * **Microphone/Talkover Mix**: This setting controls whether microphone outputs | ||
| are mixed into the Master output or only into the broadcasting output. This is | ||
| useful for preventing echo in broadcasting setups. | ||
| * **Microphone Mix Mode**: Controls the routing of microphone inputs. Refer to |
There was a problem hiding this comment.
Microphone Mix Mode-->Microphone Monitor Mode
| are mixed into the Master output or only into the broadcasting output. This is | ||
| useful for preventing echo in broadcasting setups. | ||
| * **Microphone Mix Mode**: Controls the routing of microphone inputs. Refer to | ||
| SECTION below for more details. |
There was a problem hiding this comment.
SECTION unnecessary formatting. Error prone with translations. Just Refer to section below ....
There was a problem hiding this comment.
Yes, that's just a TODO for putting an actual link to the section there. I wrote that before actually writing out the section it will link to.
|
|
||
| * **Headphone/Master Delay**: This setting allows you to compensate for the | ||
| delay between what you hear in your headphones and the master speakers. | ||
| * **Microphone Latency Compensation**: Only available when Microphone Mix Mode is |
There was a problem hiding this comment.
Please make use of the existing markup roles, specifically menuselection and guilabel (Github is bad at rendering them though), e.g.
Only available when :guilabel:`Microphone Monitor Mode` is set to :menuselection:`Direct monitor (recording and broadcasting only)`.There was a problem hiding this comment.
Will do. For now I was just focusing on the text, hence the "WIP" label
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| Stand-alone Soundcards | ||
| """""""""""""""""""" |
| stereo-to-mono DJ splitter cable (also known as a “Y cable”) plugged | ||
| into the headphone jack of a laptop or other computer. This cable divides the | ||
| stereo output from a single jack into two separate mono signals. | ||
| stereo output from a single jack into two separate mono singals. |
There was a problem hiding this comment.
I think I messed up something with merging branches or stashing with Git here.
| Using Mixxx with your built-in sound card | ||
|
|
||
| There is no need to buy any equipment other than a computer if you do not | ||
| There is no need to buy any equipment other than a computer if you do not |
There was a problem hiding this comment.
There is no need to insert white spaces before line breaks. Sphinx will add them automatically in the build. This should be reverted on all occasions across the commit.
Yep, will look into how to set this conveniently in my editor, or find another editor for working on the manual. Maintaining that manually is a big pain.
Thanks, I'll think about ways to split up the paragraphs further.
Maybe the info about DJ hardware can be moved to a new chapter, but I do think it should be early in the flow of the manual. Maybe it could be moved to the top of the chapter currently titled "Example Setups", with the "Example Setups" becoming a section in that chapter. What do you think about the new "What Mixxx Does" section? I have also removed the features list from the introduction chapter. IMO that adds little value beyond what is on the website and apparent just by looking at the GUI, but it distracts from the flow of the manual. I am thinking about removing the "What's new in version X" section too. That section is also redundant with the website. |
|
The configuration chapter is growing to be enormous. I think the Sound Hardware Preferences should have their own chapter apart from the other preference documentation. Perhaps the library preferences could be combined with the Sound Hardware preferences because those are the only preferences strictly required to be set up before using Mixxx. |
|
I think it would be helpful to take photos of actual hardware for each section describing the types of hardware. |
I like editing the manual with Atom, rst package and minimap installed. Live git support, and has a wrap guide at the 80th character by default.
Removing the feature list, as well as the |
Be-ing
force-pushed
the
sound_io_rewrite
branch
from
369503a to
1c01b4b
Compare
Be-ing
force-pushed
the
sound_io_rewrite
branch
from
ea19a25 to
12bbb08
Compare
Be-ing
force-pushed
the
sound_io_rewrite
branch
from
12bbb08 to
c8d3431
Compare
|
I asked my friend to read part of the manual and give me feedback. She thought it took too long to get to the important information in the new Getting Started chapter. Do we really need the Installing Mixxx chapter in the manual? Why would someone read the Mixxx manual before installing Mixxx? I think this information should be on the website and removed from the manual. |
Be-ing
changed the title
|
From discussing with users on the forum, I realize that we'll need lots of different signal flow diagrams to explain the various options available with different hardware and different inputs and outputs of Mixxx. @ronso0 or @esbrandt, if I draw some ugly diagrams on paper by hand, could you make nice looking pictures showing the same things? |
Sure, i´d use the graphviz graph visualization extension. We use it for visualization in the broadcasting chapter. |
The manual is not the right place for this information. People will have most likely already installed Mixxx by the time they read the manual.
The prompt for the music library directory is the first window shown when Mixxx starts with a new profile.
Be-ing
changed the title
|
There is so much to say about different ways of setting up microphones with Mixxx that I split that information into its own new chapter. Consider that chapter as just a first draft for now. |
daschuer
left a comment
daschuer
left a comment
There was a problem hiding this comment.
Some first comments.
Thank you for all the love you put into it.
|
|
||
| * **Mixxx Wiki**: For up-to-date information about supported DJ hardware, | ||
| documentation on making controller mappings, and other tips and tricks, go to: | ||
| `<https://mixxx.org/wiki/doku.php>`_ |
There was a problem hiding this comment.
Should we omit /doku.php here? For the case we change anything on the wiki software.
| * **Mixxx Community Forums**: To search for answers, post your question or | ||
| answer other DJ's questions, go to: `<http://mixxx.org/forums>`_ | ||
|
|
||
| * **Mixxx IRC Chat Channel**: Join the #mixxx channel on the |
There was a problem hiding this comment.
Is IRC stalled now? If yes, we should remove this link.
| output from its speakers to your headphones. A splitter cable can be used to | ||
| separate the stereo output of a headphone jack into two separate mono outputs | ||
| for headphone cueing, but it is recommended to use a sound card with at | ||
| least four mono outputs (for two stereo pairs). Such sound cards tend to be |
There was a problem hiding this comment.
This sentence is already stated above.
| :term:`MIDI` or :term:`HID` controller that your :term:`OS <operating system>` | ||
| has drivers to use. If your controller has an integrated soundcard, you may | ||
| choose to use a different soundcard for higher quality audio. Mixxx can also | ||
| use multiple audio devices simultaneously. |
There was a problem hiding this comment.
I would move this sentence below the splitter part. And add the Info about negative effect for the latency. That depends on the slowest device.
Give the example that using Bluetooth or USB headphones together with a low latency soundcard does not make sense.
| choose to use a different soundcard for higher quality audio. Mixxx can also | ||
| use multiple audio devices simultaneously. | ||
|
|
||
| Mixers |
There was a problem hiding this comment.
Give a hint that there might be an user with hardware volume faders only accessable by the os sound panel.
| mixed signal is sent into the computer instead of the microphone signal alone, | ||
| typically using input channels 1-2. | ||
|
|
||
| .. figure:: ../_static/direct-monitor-loopback-signal-path.png |
There was a problem hiding this comment.
I would like to make a diagram similar to the block diagram of the Roland Rubix 24 on page 26 of its manual but excluding the details in the analog domain. The parts between the A/D and D/A converters in that diagram are what matter for explaining this.
|
Note that the DJ Hardware chapter is still a work in progress at this point. |
| * :ref:`Direct monitoring<microphones-direct-monitoring>`: Recommended for | ||
| most users. This avoids the latency of software monitoring but require a | ||
| soundcard that supports this feature and can be complicated to set up. | ||
| * :ref:`Hardware mixers<microphones-hardware-mixers>`: most expensive |
There was a problem hiding this comment.
Maybe: Most expensive option for a high sound quality setup.
| option to set up with high sound quality | ||
|
|
||
| .. warning:: USB microphones are not recommended because they can only be | ||
| used with software monitoring with Mixxx. not be used |
There was a problem hiding this comment.
Some spelling problems here.
I think this warning box is too big. Are those self monitoring mic's that common? I've never seen one!
Maybe rephrase like so:
Warning: USB mics are not recommended because they can't make use of the direct monitoring feature, thus introducing latency.
I think the bit about the mics with integrated sound card should be further analysed in DJ Hardware chapter, under microphones.
There was a problem hiding this comment.
These are really common. Lots of users come to the forum confused about how to configure them with Mixxx. I will think about how to make this warning box smaller and move the details to another place.
| microphone for spoken announcements, vocals, or playing a musical instrument. | ||
| This time is referred to as "latency". | ||
|
|
||
| .. figure:: ../_static/software-monitor-signal-path.png |
There was a problem hiding this comment.
I am missing this file, manual/build/html/chapters/_static/software-monitor-signal-path.png along with some other warnings for pngs:
/home/gramanas/Code/manual/source/chapters/hardware.rst:: WARNING: image file not readable: chapters/../_static/mixxx_setup_splitter_adaptors.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:9: WARNING: Unexpected indentation.
/home/gramanas/Code/manual/source/chapters/microphones.rst:46: WARNING: image file not readable: chapters/../_static/software-monitor-signal-path.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:80: WARNING: image file not readable: chapters/../_static/direct-monitor-signal-path.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:121: WARNING: image file not readable: chapters/../_static/direct-monitor-loopback-signal-path.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:150: WARNING: image file not readable: chapters/../_static/direct-monitor-input-latency.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:187: WARNING: image file not readable: chapters/../_static/latency-measurement.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:246: WARNING: image file not readable: chapters/../_static/external-mixing-with-microphone-signal-path.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:266: WARNING: image file not readable: chapters/../_static/external-mixing-with-microphone-signal-path.png
/home/gramanas/Code/manual/source/chapters/microphones.rst:316: WARNING: image file not readable: chapters/../_static/dj-controller-with-mic-and-splitter-cables.png
/home/gramanas/Code/manual/source/chapters/quickstart.rst:4: WARNING: Unknown target name: "table of contents".
/home/gramanas/Code/manual/source/chapters/user_interface.rst:106: WARNING: image file not readable: chapters/../_static/Mixxx-200-Latenight-Deck-Waveform.png
I am not familiar with rst so I might be doing something wrong, in that case discard the comment!
There was a problem hiding this comment.
Those diagrams have not been made yet. One step at a time :)
| setup without the latency issue of | ||
| :ref:`software monitoring <microphones-software-monitoring>` and cheapest | ||
| to set up with good sound quality. | ||
|
|
There was a problem hiding this comment.
Rephrase: It is the easiest and cheapest to setup, without the latency issue of software monitoring and with good sound quality.
|
|
||
| Removing tracks from the Mixxx library will **not** physically delete them from | ||
| your drive. However it does delete extra metadata Mixxx might have (such as | ||
| hotcues and the beatgrids), and removes links to playlists or crates. |
There was a problem hiding this comment.
I am not sure if links to playlists are removed, if you hide a track.
At least we had a version where unhide restores the playlist and crate membership.
| from the library will appear here. | ||
| #. Select the tracks you want to remove, or use the :guilabel:`Select All` | ||
| button. | ||
| #. To confirm you want to permanently remove these tracks from the library, |
There was a problem hiding this comment.
If you purge a track, it will be back after the next library scan. It purges all the metadata, hidden tracks keep their metadata.
|
@daschuer right now I am most interested in feedback on the introduction and microphones chapters. |
| WAV and AIFF files are uncompressed and take up much more space. | ||
|
|
||
| Lossy formats take up less storage space on your computer than lossless | ||
| formats at the expense of reducing sound quality. However, modern hard drives |
There was a problem hiding this comment.
It is up to the user to decide if the space is sufficient for Flac. This sentence should be removed.
We can simply just say in the flac region above: "flac is the recommended format if disk space is not an issue."
There was a problem hiding this comment.
I think saying "if disk space is not an issue" is too vague. I think it is helpful to give the perspective that modern HDs & SSDs can store many thousands of tracks in FLAC.
There was a problem hiding this comment.
Maybe you can find an other less meaningless sentence. What do you like to express.
"Use Flac, there should be now excuses, because of missing HD space"?
I have a not that recent external HDD and it is occupied with mp3s. We may also consider that not all users have a high speed internet connection.
You may give a real example:
A typical USB Hard disk has 1 TB and can store more than 30000 FLAC files.
There was a problem hiding this comment.
Maybe you can find an other less meaningless sentence. What do you like to express.
"Use Flac, there should be now excuses, because of missing HD space"?
I have a not that recent external HDD and it is occupied with mp3s. We may also consider that not all users have a high speed internet connection.
You may give a real example:
A typical USB Hard disk has 1 TB and can store more than 30000 FLAC files.
There was a problem hiding this comment.
Giving actual numbers is a good idea. A 4 minute 44.1 kHz 16 bit FLAC file takes about 25 MB. A 4 minute 320 kbps CBR MP3 takes about 9.2 MB. Assuming an average track length of about 4 minutes, a 1 TB drive would fit about 42000 FLAC files or 115000 MP3s.
| and cons: | ||
| * :ref:`Software monitoring<microphones-software-monitoring>`: Cheapest and | ||
| simplest to set up, but there is a disorienting delay, referred to as | ||
| "latency", between sound going into the microphone and hearing it come out |
There was a problem hiding this comment.
To actually hear the disorientating delay is not an option.
For this setup it is recommended to configure Mixxx to not hear the own voice.
This can be done by removing the mic sound from headphones and master output, as the use-case requires.
There was a problem hiding this comment.
Yes, I forgot that was an option. I will revise this to say that users cannot hear themselves without latency. If they don't want to hear themselves that is not an issue.
| "latency", between sound going into the microphone and hearing it come out | ||
| speakers or headphones. | ||
| * :ref:`Direct monitoring<microphones-direct-monitoring>`: Recommended for | ||
| most users. This is the easiest and cheapest to set up with good sound |
There was a problem hiding this comment.
We can't judge as bout cheep, here. It is cheep to use the laptops build in mic that's all.
There was a problem hiding this comment.
Yes we can. A quality dedicated soundcard that supports direct monitoring is cheaper than a digital hardware mixer with a built-in soundcard. A mic built into a laptop is surely not going to sound as good a dedicated mic and soundcard.
| most users. This is the easiest and cheapest to set up with good sound | ||
| quality and without the latency issue of software monitoring. | ||
| * :ref:`Hardware mixers<microphones-hardware-mixers>`: Most expensive option | ||
| to set up with high sound quality. This does not have the latency issue of |
There was a problem hiding this comment.
We do not know the sound quality of an external mixer.
Can it be better than Mixxx?
There was a problem hiding this comment.
I don't understand your question. Did you read the whole chapter? The sound quality of the mixer is not the bottleneck if the user is using a bad quality soundcard with it.
There was a problem hiding this comment.
The sound quality is not related to microphones-hardware mixers an should be removed from this sentence.
| to set up with high sound quality. This does not have the latency issue of | ||
| software monitoring. | ||
|
|
||
| .. warning:: USB microphones are not recommended. These devices have their own |
There was a problem hiding this comment.
This warning is to prominent for me. I think using a USB mic is a valid use case for broadcasting setups. I think it is quite common to have USB headsets.
There is not much a difference between plugin a mic into a soundcard or using an USB mic.
The only issue is that the soundcard might be poor.
It would be better to tell here how to configure an USB headsets.
There was a problem hiding this comment.
I think this warning is as prominent as it needs to be. For similar costs as USB microphones users can get a soundcard capable of direct monitoring and a regular microphone.
There was a problem hiding this comment.
That is not true. There are real cheap usb headsets available < 20 €
There are also user we which have already an USB headset.
There was a problem hiding this comment.
I am doubtful users who want to use a headset with Mixxx will bother to read the manual before buying hardware or care what it recommends. Those are not the users who this warning is for.
Typical USB microphones cost $100-150. For a similar price a user could get a Behringer U-Phoria UMC22 and a decent microphone that would let them use direct monitoring.
There was a problem hiding this comment.
You are fully right, If a user wants to spend a reasonable amount of money, he should not go with a USB headset solution. But there is no big disadvantage, using an existing headset for broadcasting, if the own voice is passed only to the sidechain.
So we just need a sentence that expresses this more differentiated.
For a life setup a cheep headset is almost useless.
There was a problem hiding this comment.
I will clarify this in the Software Monitoring section, but I don't think this warning box should have any more detail.
|
I have been thinking about replacing the word "soundcard" with "audio interface". "Soundcard" confuses users because sometimes they do not understand that it can refer to devices that are not PCI cards. |
|
I am pro audio interface but we should keep the word soundcard for reference and indexing somewhere. |
"Sound card" is confusing because it implies a device shaped like a card, but PCI sound cards are rare today. Also, searching the web for "audio interface" and "sound card" show different kinds of products.
|
I had not thought about the different search results from "audio interface" versus "sound card" before, but yes, you are right. I think Mixxx's use of "sound card" has been implicitly directing users to buy hardware that does not follow our own documentation's recommendations. |
|
Okay, I think I am (just about) done with the Using Microphones chapter. Please review it. |
|
I have added to the DJ Hardware chapter and split the Example Setups section into its own chapter. If you have feedback on the recent changes, please do share. I have merged this already to get a build online at ReadTheDocs so we can answer users' common question of how to setup microphones. |
4 participants
Adding more background information to make Mixxx more approachable to new DJs and documenting changes introduced by mixxxdj/mixxx#1279 . I still have a lot of organizing, editing, and writing to do.