Guide for end users, installers, and systems integrators.

The Podcast In a Box needs the following to work:

(1) Network Interface: ethernet card and LAN, correct routing and DNS settings
(2) Audio Capture: supported audio card, input cabling and levels
(3) Audio Encoding: select mono or stereo, 16kbps to 128kbps mp3 bitrate
(4) Hardware: 128M memory, 4GB disk space and 500Mhz processor
(5) Podcast Production: user account and password for the server
(6) USB device: usb card, usb key device, usb extender cabling
(7) Software: latest production version of the podcast in a box software packages

Additionally, to install Podcast In a Box:

(8) CD-ROM drive configured as the first BIOS boot device for the computer
(9) Podcast In a Box installer image, burned to a CD in raw/image format
(10) Network access, microphone or line in and usb key/server account for testing.

Common usage problems and solutions:

inserted key does not beep

if it never happens: sometimes there is no speaker installed!
usb card or device is not supported. even keys without a metadata.xml file should beep.
apparently some usb keys ship with strange files that confuse the software. try an entirely blank key. if you have a key like this, erase any "special" files before copying the metadata.xml

inserted key beeps but does not upload

very common: double check the user name and password in /piab/metadata.xml on the key!

created files are still available on the system in /opt/wiab/binary_data/icecast/items, you can use an sftp/scp client logged in as user piab to fetch them and then upload manually.
we're working on a more user-friendly solution for this

check network settings, that the sound card works (if no sound card is detected the capture process dies), and that darkice and icecast are running. check the global log for error messages.

uploaded file does not have any sound

check that the capture device is the same as where the 1/8" cable goes in: line (usually blue) or mic (red)
increase the level using the admin web page, some cards have both a capture, mic, and mixer levels which you change individually using alsamixer.
check the audio input using headphones or a stereo

uploaded file sounds bad

it might be clipping, try decreasing the capture level or switching from mic to line input.
generally speaking for voice use mono capture, for radio use stereo
for voice 32kbps is fine, for radio use 128kbps
check the audio input/balance using headphones or a stereo
make sure audio card sample rate is 44100 instead of 22050 or 11025.
many times microphone input is mono only, try switching to line.
make sure the cable is stereo with three connectors at the tip, mono cables only have two

Common installation problems and solutions:

computer won't boot from cdrom, never shows splash screen

computer is not configured to boot off CD-ROM: press delete or F1 during boot up, then select CD-ROM as the first boot device. on many BIOSes this is in "Advanced BIOS Options"
using a USB CD-ROM drive: select "USB CDROM" instead. some computers only support USB 1.1 and it will take an incredibly long time to boot, try a different USB port, or temporarily install a USB 2.0 card.
CD-ROM drive cable is loose or isn't plugged in :-) for some reason I do this a lot
CD installer image was burned as a file, not an image: to test, put the cd in a computer and look at the contents: it should have a bunch of files and folders with strange names on it. If it contains a single large file, the installer image was burned as a file and it will not work.
CD media or CD-ROM drive is faulty. Try the CD on another computer, or replace the CD-ROM drive.

computer boots from cdrom, shows splash screen, but never reaches the installer program

there might not be enough memory or processor might be very slow.
CD media is slightly faulty, the errors cause it to go slowly. you can hear it spinning up and seeking over and over.
computer might not support linux. unlikely unless its an older laptop. broken acpi can cause this, try adding acpi=off to kernel command line

audio page: there are no options when detecting a sound card except "probe for legacy"?

audio card is not supported: remove the existing card or tape over the inputs so it isn't used accidentally, then install a new sound card and try again.
builtin audio card is disabled in BIOS: enable the audio device in the bios (how exactly to do this depends on the computer model)

network page: it does not detect any IP or name server

no network card installed
network cable is not plugged in to computer or switch/router
there are multiple network cards and only one is plugged in: remove all but one network card. most common if there is a builtin network card and a faster "upgrade" card.
wireless is not supported yet except using Ubuntu manual configuration.

USB page: it does not beep or detect usb key

the usb port is not plugged in: some front panel usb ports require to be plugged into the motherboard, try one of the ones in the back.
usb card is not supported: try replacing usb card with another one
usb key does not work: some keys just do not work for some unknown reason. try a known working key or a key of a different brand.

Install page: don't forget to write down or memorize the password, the only way to recover it is to reinstall!

Additional notes for MPEG4 video podcast in a box

(1) Video Capture: video for linux capture card
(2) Video Encoding: select 320x240 or 640x480 resolution
(3) Hardware: 512M memory, 20GB disk space and 2Ghz processor

Common problems and solutions:

Video file is a blue screen

make sure the camera is plugged in and turned on. many camcorders will turn themselves off if no tape is inserted.
run Settings -> Video Setup and select composite or s-video input

No audio

for most installs, plug the microphone into the computer's sound card rather than the audio input on the video capture card

Video file won't play

the default codec is 320x240 MPEG4 divx/aac which should play on pretty much anything. if your files do not play please post a message on the help forum

Basic Usage

Definitions

Episode: individual recording and its description, which can be part of a podcast.
Program: a scheduled event to create an episode in the future.
USB Key: a usb thumbdrive with an xml file containing user account information, when inserted the recording starts, when removed recording stops and an episode is created and uploaded to the user's account on the media management server.
Icecast radio/live monitor: every podcast in a box runs an internet radio stream on port 8000. The stream is firewalled off until you log into the web user interface. You can choose to turn off the firewall during install if you are running an internet radio station.

Developer Notes

Introduction

If you want to modify the Podcast in a Box code please start here. Please ssh into the system and run 'sudo apt-get install bp-piab-developer-tools' This will install several developer tools and scripts.

System Layout

Everything used by the Podcast in the Box is stored underneath the /opt/wiab directory. All files created or modified after installation are either stored in the /opt/wiab/binary_data directory or the /opt/wiab/text_data directory. If you want to modify the operation of the podcast in a box, you probably want to start in the /opt/wiab/custom directory. The directory /opt/wiab/custom/bin holds executable scripts. The lib directory stores system libraries that are used by these scripts. Most of these files are written in the Perl programming language. Scripts in /opt/wiab/custom/bin are run throughout the uptime of the system. The web administrator interface is a Ruby on Rails application. The rails application files are in the /opt/wiab/custom/rails/ssl directory.

Programming in Perl

Here are a few of the tricks we use when writing Perl programs.

perl -c path-to-program # this verifies the syntax of the program is correct
perl -I/opt/wiab/custom/lib -MWIAB/Foobar -e 'print WIAB::Foobar::some_function();' # this runs the some_function subroutine in the WIAB/Foobar.pm file

Programming in Ruby (and Rails)

One of the most powerful things about Ruby on Rails is console mode. You are actually able to access (and manipulate) your web application data on the live system. This makes it very easy to check information and also make simple updates to your data if necessary.

$ cd /opt/wiab/custom/rails/ssl
$ sudo su piab
$ ./script/console production # careful, this is your live data
$ console> u = User.find :first, :conditions => [ 'login = ?', 'chris' ] # Find the user named chris
$ console> u.firstname
'Chris'
$ console> u.firstname = 'Christopher' # change first name to Christopher
$ console> u.save! # save it back to the database

This is a cool feature. It also means we can write scripts which utilize the powerful ORM (Object Relational Mapping) features of Ruby on Rails. For example, you could easily write scripts to upload all files using SCP. We might put this in our cronjob file to automate publishing into our custom CMS.

Submitting Changes

Once you have made changes you can submit them to Box Populi for consideration. Run /opt/wiab/custom/bin/bp-make-patch to create a patch of changes. Run /opt/wiab/custom/bin/bp-submit-patch to submit that patch. You can use the -m switch and provide a message or the program will prompt you for one. You can use the -s switch to specify that the patch should be private; for example if you found a security issue that should not be publicly displayed on our patch.corp.boxpopuli.com website. You can submit a maximum of three patches a day as a developer from the same IP address.

Tools

Developers need an editor. We ship pico and vim. To install emacs run "sudo apt-get install emacs".