From owner-freebsd-doc@FreeBSD.ORG Thu Jul 19 03:30:04 2007 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id A925616A406 for ; Thu, 19 Jul 2007 03:30:04 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freebsd.org [69.147.83.40]) by mx1.freebsd.org (Postfix) with ESMTP id 8697213C4A6 for ; Thu, 19 Jul 2007 03:30:04 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.1/8.14.1) with ESMTP id l6J3U4tg020029 for ; Thu, 19 Jul 2007 03:30:04 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.1/8.14.1/Submit) id l6J3U4Do020028; Thu, 19 Jul 2007 03:30:04 GMT (envelope-from gnats) Resent-Date: Thu, 19 Jul 2007 03:30:04 GMT Resent-Message-Id: <200707190330.l6J3U4Do020028@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Ben Kaduk Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 9043F16A401 for ; Thu, 19 Jul 2007 03:23:06 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (groups.freebsd.org [69.147.83.33]) by mx1.freebsd.org (Postfix) with ESMTP id 8031613C491 for ; Thu, 19 Jul 2007 03:23:06 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (localhost [127.0.0.1]) by www.freebsd.org (8.14.1/8.14.1) with ESMTP id l6J3N6es059479 for ; Thu, 19 Jul 2007 03:23:06 GMT (envelope-from nobody@www.freebsd.org) Received: (from nobody@localhost) by www.freebsd.org (8.14.1/8.14.1/Submit) id l6J3N6xV059478; Thu, 19 Jul 2007 03:23:06 GMT (envelope-from nobody) Message-Id: <200707190323.l6J3N6xV059478@www.freebsd.org> Date: Thu, 19 Jul 2007 03:23:06 GMT From: Ben Kaduk To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.0 Cc: Subject: docs/114718: grammar, etc. in handbook/multimedia (part 1) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 19 Jul 2007 03:30:04 -0000 >Number: 114718 >Category: docs >Synopsis: grammar, etc. in handbook/multimedia (part 1) >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Thu Jul 19 03:30:03 GMT 2007 >Closed-Date: >Last-Modified: >Originator: Ben Kaduk >Release: 7.0-CURRENT >Organization: >Environment: System: FreeBSD prolepsis.scs.uiuc.edu 7.0-CURRENT FreeBSD 7.0-CURRENT #1: Sun Apr 1 16:59:00 UTC 2007 kaduk@prolepsis.scs.uiuc.edu:/usr/obj/usr/src/sys/GENERIC i386 >Description: I've been sitting on this for a while, and I'm nowhere near the end of the chapter. Since I've already accumulated a fair number of changes, I'll batch them up a bit. Justifications/explanations for changes follow: experimentation: this seems marginally better grammar, though the meaning is still a bit awkward ports collection: clear grammar change sample applications-->\0: unnecessary information-->content: seems more consistent with modern use this document-->hardware notes: why use pronouns when we could be non-ambiguous? adding-->add: tense correction we-->you: the reader is the interested party [kernel configuration syntax]: we just gave some information here; NOTES is the definitive source [non-PnP ISA stuff]: we only care about sound cards, here, so mention ``sound card'' first and then use ``card'' unadorned; at system boot feels awkward here, to me [axe snd_sb16(4)]: I see no reference to this at this time as well as the following in-->and these to: less awkward [sound driver manual page]: be explicit here (I had to think for a while to figure out what was meant) show up-->are listed: more formal is chosen-->was chosen: the past tense seems more appropriate to me properly coupled-->...connected: ``coupled'' isn't quite right; be specific about what hardware topology needs to exist for playback to work [cat >/dev/dsp]: new idea; new paragraph. Also, use ``another'' because we already gave one way to test the sound card (play a CD) [remove ``unsupported subdevice XX'']: this is a relic of the MKNOD era (this faq was present in the first revision of this chapter) set-->enabled: the channels are enabled; the number of them is set playback channels-->playback: the playback is multiplexed, not the sound card's channels (it is the channels of the programs playing audio which are multiplexed) to the user-->to a program...:something has to ask for /dev/dsp, and the programs are what do it. Actually, we could probably remove this, since devfs is essentially obligatory these days [default mixer levels]: general cleanup. Give sample volume of 50 because 75 is the default and setting to 100 can lead to distortion (so ariff@ claims, and I believe) >How-To-Repeat: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/multimedia.html >Fix: Patch attached with submission follows: --- chapter.sgml.orig.0 2007-07-06 15:03:22.000000000 -0500 +++ chapter.sgml.orig 2007-07-18 22:13:15.000000000 -0500 @@ -27,12 +27,12 @@ applications allowing you to edit your recorded audio, add sound effects, and control attached MIDI devices. - With some willingness to experiment, FreeBSD can support + With some experimentation, FreeBSD can support playback of video files and DVD's. The number of applications to encode, convert, and playback various video media is more limited than the number of sound applications. For example as of this writing, there is no good re-encoding application in the - FreeBSD Ports Collection, which could be used to convert + FreeBSD Ports Collection that can be used to convert between formats, as there is with audio/sox. However, the software landscape in this area is changing rapidly. @@ -52,8 +52,7 @@ - Methods to test that your card is working using - sample applications. + Methods to test whether your card is working. @@ -78,7 +77,7 @@ - How to rip CD and DVD information into files. + How to rip CD and DVD content into files. @@ -140,7 +139,7 @@ FreeBSD supports a wide variety of both PCI and ISA cards. Check the supported audio devices list of the Hardware Notes to see if - your card is supported. This document will also mention which + your card is supported. The Hardware Notes will also mention which driver supports your card. @@ -190,14 +189,14 @@ Configuring a Custom Kernel with Sound Support - The first thing to do is adding the generic audio driver - &man.sound.4; to the kernel, for that you will need to + The first thing to do is add the audio framework driver + &man.sound.4; to the kernel; for that you will need to add the following line to the kernel configuration file: device sound - Then we have to add the support for our sound card. - Therefore, we need to know which driver supports the card. + Next, you have to add the support for your sound card. + Therefore, you need to know which driver supports the card. Check the supported audio devices list of the Hardware Notes, to determine the correct driver for your sound card. For @@ -208,24 +207,24 @@ device snd_emu10k1 Be sure to read the manual page of the driver for the - syntax to use. Information regarding the syntax of sound - drivers in the kernel configuration can also be found in the + syntax to use. The explicit syntax for the kernel configuration + of every supported sound driver can also be found in the /usr/src/sys/conf/NOTES file. - Non-PnP ISA cards may require you to provide the kernel - with information on the sound card settings (IRQ, I/O port, - etc). This is done via the - /boot/device.hints file. At system boot, + Non-PnP ISA sound cards may require you to provide the kernel + with information on the card settings (IRQ, I/O port, + etc), as is true of all non-PnP ISA cards. This is done via the + /boot/device.hints file. During the boot process, the &man.loader.8; will read this file and pass the settings to the kernel. For example, an old Creative &soundblaster; 16 ISA non-PnP card will use the - &man.snd.sbc.4; driver in conjunction with snd_sb16(4). For this card the following lines have to be added to + &man.snd.sbc.4; driver. For this card the following lines must be added to the kernel configuration file: device snd_sbc device snd_sb16 - as well as the following in + and these to /boot/device.hints: hint.sbc.0.at="isa" @@ -239,12 +238,13 @@ The syntax used in the /boot/device.hints file is covered in the - sound driver manual page. + &man.sound.4; driver manual page and the manual page + for the driver in question. The settings shown above are the defaults. In some cases, you may need to change the IRQ or the other settings to - match your card. See the &man.snd.sbc.4; manual page for more - information. + match your card. See the &man.snd.sbc.4; and &man.snd.gusc.4; + manual pages for more information about these cards. @@ -269,14 +269,14 @@ kld snd_ich (1p/2r/0v channels duplex default) The output from your system may vary. If no - pcm devices show up, go back and review + pcm devices are listed, go back and review what was done earlier. Go through your kernel configuration file again and make sure the correct - device is chosen. Common problems are listed in . If all goes well, you should now have a functioning sound - card. If your CD-ROM or DVD-ROM drive is properly coupled to + card. If your CD-ROM or DVD-ROM drive's audio-out pins are properly connected to your sound card, you can put a CD in the drive and play it with &man.cdcontrol.1;: @@ -286,8 +286,10 @@ role="package">audio/workman can provide a friendlier interface. You may want to install an application such as audio/mpg123 to listen to - MP3 audio files. A quick way to test the card is sending data - to the /dev/dsp, like this: + MP3 audio files. + + Another quick way to test the card is sending data + to /dev/dsp, like this: &prompt.user; cat filename > /dev/dsp @@ -317,12 +319,6 @@ - - unsupported subdevice XX - One or more of the device nodes was not created - correctly. Repeat the steps above. - - sb_dspwr(XX) timed out The I/O port is not set correctly. @@ -372,9 +368,9 @@ sound device with a certain application. FreeBSD lets you do this through Virtual Sound - Channels, which can be set with the &man.sysctl.8; + Channels, which can be enabled with the &man.sysctl.8; facility. Virtual channels allow you to multiplex your sound - card's playback channels by mixing sound in the kernel. + card's playback by mixing sound in the kernel. To set the number of virtual channels, there are two sysctl knobs which, if you are the root user, can @@ -406,7 +402,8 @@ where x is 0 to 3 if hw.snd.pcm.0.vchans is set to 4 as in the above example. On a system using &man.devfs.5;, the above will - automatically be allocated transparently to the user. + automatically be allocated transparently to a program + that requests /dev/dsp0. @@ -424,17 +421,17 @@ The default values for the different mixer channels are hardcoded in the sourcecode of the &man.pcm.4; driver. There are - a lot of different applications and daemons that allow - you to set values for the mixer they remember and set - each time they are started, but this is not a clean - solution, we want to have default values at the driver - level. This is accomplished by defining the appropriate - values in /boot/device.hints. E.g.: + many different applications and daemons that allow + you to set values for the mixer that are remembered between + invocations, but this is not a clean solution. It is possible + to set default mixer values at the driver level — this + is accomplished by defining the appropriate + values in /boot/device.hints, e.g.: -hint.pcm.0.vol="100" +hint.pcm.0.vol="50" This will set the volume channel to a default value of - 100, when the &man.pcm.4; module is loaded. + 50 when the &man.pcm.4; module is loaded. >Release-Note: >Audit-Trail: >Unformatted: