SermonAudio FTP Client BETA 0.9.4

Welcome to the SermonAudio FTP Client! This is a desktop program to help make uploading sermons to SermonAudio.com easier. (You must be a broadcaster with a full broadcaster account to use this program.) This software is free for anyone to use, and published under the GNU Public License (with full source code available). This software was not developed by SermonAudio, so please do not contact them about it. This software was developed by Scott McMahan to help him manage uploads, and has been released under the GPL in case any other broadcasters can benefit from using it.

BETA SOFTWARE: This software is currently still in beta testing. As far as I know, all the features that are implemented work correctly, so the software should be usable. But not all features are implemented. There are also numerous glitches and other issues that will only be shaken out by using the software.

A broadcaster's experience: Joshua M. Espinosa of Being Transformed was a new SermonAudio broadcaster with over a thousand sermons to upload. He used this software because it was compatible with the Apple Mac, and because the software "made it easy to place the tags which SermonAudio is looking for in their files." Because he used an early beta version of the program, he provided invaluable feedback. He said of the back-and-forth process: You have shown what every end user would like, An open ear to discussion and enhancements as to what is "needed" to make the software more user-friendly. Thank you.

System requirements: Your computer must be able to run Java programs. Many operating systems can do this out of the box. Others require you to download and install the Java runtime environment. Once you do this, you should be able to double-click the main program and have it run. Note that I do not have the capability to test my software on all combinations of operating systems and Java runtimes, but have tried to cover the major ones. I have tested with Red Hat Linux Fedora 10, Apple Mac OSX under both the built-in, native Java and also under SoyLatte and X11, and Windows 2000 in a VirtualBox instance.

Mac users: Note that Apple does not support Java 1.6 "out of the box" on 10.4 or lower. You have to install a third-party Java build (like Soylatte). This requires a lot of technical expertise, and you can't just double-click the JAR file and run the program. Because of this, I am now including a Java 1.5 build of my program in the JAR file saftpclient_java15.jar. If you double-click this in 10.4 or lower, it should run fine. Note than 10.5 or higher has Java 1.6 available, but I do not have a Mac that runs 10.5 available to test with.

Contact: Scott McMahan, the developer, or go to my web site for more information. (SermonAudio has nothing to do with this program, so do not contact them. If you have any questions, bug reports, feature requests, etc contact me directly.)

This web page is the documentation for the program.

DOWNLOAD

Download the current program distribution (BETA 0.9.4).

HOW DO I USE THIS PROGRAM?

INSTALL: Create a directory on your computer and unzip the distribution file in it. The distribution consists of a bunch of Java .jar files that all need to be in the same directory.

RUN: You must have a Java runtime environment available to run this program. If you are lucky, you can double-click saftpclient.jar and your computer will know how to run the program. If not, you can still be lucky if you download and install Sun's Java environment, and it automatically configures your system. Then you can can double-click saftpclient.jar and your program will run. Hopefully the program will be easy to run on most computers.

You need Java 1.6 available. Mac users who have 10.4 or earlier are stuck on 1.5, so I have included saftpclient_java15.jar for them. If you can run the 1.6 version, it is the preferred version.

Otherwise, a simple run.sh file is provided for Linux and Mac users (and you need to edit this to use the path to Java on your system). The program is self-contained, so all you really need to do is java -jar saftpclient.jar to run it if Java is already set up. A similar run.bat could be adapted on Windows. If you do not have a Java JRE available, it can be downloaded from java.sun.com.

ACTIVATE: If you have not activated the FTP feature for your broadcaster account at SermonAudio, then do that first. You will get an e-mail with information which you'll need in the next step.

CUSTOMIZE: Start the program and choose the first menu entry, "Manage Defaults and Account Info". The "broadcaster" and "password" fields are from the e-mail. The FTP site is also in the e-mail, but is unlikely to change. This program assumes you put all your MP3s in a single directory, so point the "MP3 folder" field to that directory.

SermonAudio has a fixed format for speakers: You must specify them for uploads exactly like you set them up. Because of this, the program manages a speaker list for you. Put your official speaker names in this list exactly how they should be on uploads. From then on, you may pick your speakers out of the list and not worry about getting the speaker exactly right. There is also a category list, which already has the most common categories available.

The queue size setting controls how many slots are in the upload queue. The default is 100. Uploads are done in the background so you can keep working, so when you upload a file, it is placed in the queue. If the queue fills up, the program waits until the queue has free slots available. Most of the time you should not have to change this, but if you are uploading more than 100 sermons in a row, you may want to increase the queue size.

Also, you may change the font size so the program will be readable on your display. After this, you can save your defaults. (Note: The new queue size and font size will only be in effect after you restart the program.)

BACKUP: The program creates three files: defaults.dat, reminder.dat, and uploads.dat. Back these up.

UPLOAD: A tour of the user interface.

Initial screen:

The initial screen has the main menu. Each item in the menu opens a new dialog.

The log window is where messages appear from the upload queue. When you upload a sermon, it is placed in an upload queue which runs in the background. You may continue working while the upload takes place.

Defaults screen:

The first thing you need to do is set the defaults.

• Broadcaster: Your SermonAudio broadcaster name. (You see this in the e-mail you got when you turned on the FTP feature.)
• Password: Also provided by SermonAudio in the e-mail.
• FTP site: This is in the e-mail, but is unlikely to ever change.
• MP3 folder: This is the folder on your local computer where you have the MP3s you want to upload. (Note: Multiple folders, and nested sub-folders, are not supported.)
• Speaker list: SermonAudio requires you to spell your speaker names exactly to match their existing list of speakers when you do an upload. You can put your list of speakers here, make sure they are proofread and spelled correctly, and then pick them from a list when you fill out the tags for an MP3.
• Category list: Similar to speakers, SermonAudio has a fixed list of categories for uploaded sermons. You probably will never need to change this list, since the default list has most of the main categories. (Note: SermonAudio calls it category on their web site, and event code in the e-mail. I use the former because it's what you're used to seeing on the web site.)
• Queue size: You can leave this alone unless you need to make it bigger. If you are uploading more than 100 files at a time, you can increase the queue size. (This change does not take effect until you restart the program.)
• Font size: You may set the font size to make the user interface readable on your screen. (This change does not take effect until you restart the program.)

Set speaker names:

Once you have set your speaker names in this list, you never have to worry about mistyping them.

Set categories:

You can set the categories similarly to the speakers. The default list covers the main categories at SermonAudio, so you may not need to change it.

Warning: The category is part of a file name. Be aware that some operating systems do not allow some characters in valid file names. If you stick to normal characters, this won't be a problem, but the program has no way to tell if a character is valid for your particular operating system.

View, edit, and upload MP3s:

In this dialog, you may select as many MP3s as you want to upload. (If you view or edit the tags when multiple MP3s are selected, you'll see only the first one.)

View MP3 tag:

You could view the tags in your favorite MP3 player, but this viewer shows you the special SermonAudio field names.

Edit ID3 tag:

You could use any ID3 tag editor, such as your favorite MP3 program or the options that set the tags in the world's best MP3 encoder lame, but they do not use SermonAudio's convention for using standard MP3 tags to store sermon data. This MP3 tag editor lets you set the fields. Note that you do not type in (and do not have a chance to mess up) the speaker name because you select from your predefined list. Also, this dialog enforces any of SermonAudio's restrictions on these fields (such as that the title and subtitle can't be all uppercase).

Edit All ID3 tags:

You can set all the ID3 tags in the MP3 directory at the same time. This is useful to set the speaker name for all the tags at once. It's also useful to set all the subtitles the same if you have a series. Less chance of mistyping. You may select which tags to edit, so you don't have to edit all of them. If you don't edit a tag, and it is already set, the old value is preserved.

Rename files:

You select the date with the drop-down calendar.

SermonAudio has a way to set the date of a sermon using a special naming convention for file uploads. You could manually rename a sermon. Or, you could use this dialog box and pick the date and category and let the program rename the file correctly for you.

To rename the file, you must select both the date of the sermon and the SermonAudio category. As a guess, the program looks at the date of the MP3 file for the starting point. You can then go back to the previous Sunday (or Wednesday), or select the actual date in the case of historical sermons.

Logging: The program writes to the log file uploads.dat when you (successfully) upload a sermon. You can click the See Previous Uploads button. Because of time pressures, the previous uploads are simply printed in the log window. I wish I could have done something fancy.

Other functionality:

BETA: The reminders/scheduled uploads functionality is not yet implemented.

ID3 TAGS: This program reads and writes only version 1.x ID3 tags, since SermonAudio accepts only version 1.x tags in its uploads. (ID3 is the name of the common naming convention that stores data in a MP3's comments field. The difference between 1.0 and 1.1 was to add a track sequence number for albums. This does not apply to SermonAudio uploads, so I call it 1.x.) If you create normal 1.x tags with an MP3 encoder (like lame), or add the tags with this program itself, this will not be an issue. However, if you try to use this program with MP3s that have other tag formats, you won't be able to. I do not support multiple sets of tags in one MP3, nor do I support the 3.x tag format. But if you just use the program normally, this won't be an issue for you.

Note also that this program always presents ID3 tag fields with their SermonAudio names, not the underlying generic ID3 field names. So you don't have to remember which tag gets which value.

LOG WINDOW: The program transfers files in the background so you can keep working. The log window is where the background FTP queue tells you what it is doing.

CAN I USE THIS WITH MORE THAN ONE BROADCASTER? Sort of. Just create the defaults for the first broadcaster as usual. Then move the *.dat files someplace, and create another set of defaults for the next broadcaster, etc. Move the set of *.dat files into the main program folder for the broadcaster. If the ability to upload for multiple broadcasters is needed, let me know and I will work on something. Most SermonAudio broadcasters don't seem to use multiple accounts, but I think a few of them do.

WHY ARE SERMONS UPLOADED ONE AT A TIME IN A QUEUE? Most (American) ISPs severely throttle upload bandwidth, even if they allow faster download speeds. The program could upload more than one sermon at a time, but it would significantly cripple your Internet connection while you were using it because the different uploads would be consuming the little bandwidth available. (If you want to have a multiple-upload queue, that's possible. Just get someone who knows Java to replace the single-queue start with an Executor that starts a bunch of them. The queue itself is thread-safe, meaning you could have as many queue-processing worker threads as you wanted. I did not implement this because of time and the fact that most upload connections are throttled so people wouldn't want it.)

JAR FILES: I use several packages from other sources (all open source software). The file saftpclient.jar is my main program. The other files: commons-net-2.0.jar (etc) provides FTP support, JID3.jar provides MP3 tag support, layouts.jar makes creating dialog boxes easier, looks-2.2.1.jar provides better user interface support, and ostermillerutils_1_07_00.jar provides the routines I use for comma-separated value lists. Also, jcalendar-1.3.3.jar provides the calendar control.

LICENSE: This software is open source and has been released under the Gnu Public License. Anyone is free to use and enhance this software.

OTHER LANGUAGES: If you want to create versions of this program for other language, all strings which appear in the user interface are in a single Java source file. They could be translated to any English-like (left-to-right) language. If this becomes an issue, I can factor the strings out so they are in a file instead of in Java source code so you can change the language without having to compile the code. Porting to a language that is right-to-left or doesn't use the Roman alphabet would be more difficult and probably require rewriting the user interface.

FEATURE REQUESTS: You can send me the specifications for new features, but there are no guarantees. I'm writing this program in my spare time. This is GPL software, so you can get any programmer who knows Java to modify the source. Please send me a copy of what was done.

DEVELOPERS: You can download the code and do whatever you like. If you do something, let me know.

• Download source code:
  • BETA 0.9.4.
  • BETA 0.9.3.
  • BETA 0.9.2.
  • BETA 0.9.1.
• View the current JavaDoc for this project.

BETA 0.9.4 RELEASE NOTES

What has changed since the previous release:

• From here: I am becoming a little pressed for time. I have given up trying to make the primitive, almost useless JTable control work, which is why the Edit All ID3 tags dialog is so primitive. I was going to enable editing tags in a table and writing them out. I have yet to find a GPL replacement control that does what the useless JTable does not do. Similarly, it would take months of work on weekends, etc where I have just an hour or two to get a JTree control working to make the reminder/scheduled uploads feature work. I am not sure I have time to put this much work into it, or just punt again like I did with JTable. Also, I am trying to get SermonAudio to publish their FTP processing response to an RSS feed. There are numerous Java RSS feed packages and I could poll this feed to give real-time feedback about what happened when the file was FTPed.
• Fixed the issue where you could exit the program when the queue was still running. The program now will not exit until the queue has been processed (or you do something extreme to terminate it). A more friendly program would ask, but I don't have time to write a worker thread that could stop the queue, since (I hope) this would not be a feature people would want to use. To fully implement this, I would have to have the queue watch a flag that the worker thread would set. When you closed the application, you would be prompted to wait for the queue or stop it.
• New feature: display log of uploads. I had to punt on this: It just prints to the log window. I have not had time to do anything else with it.
• New feature: uploads are logged.
• New feature: added the ability to edit all ID3 tags at once.
• BUG FIX: It is possible for the user to delete all the items in the speaker and category lists. Since drop-down choosers depend on this list, and there would be a crash if it was empty, the routines that give this list to drop-downs check to see if it is empty and put a placeholder so there's no crash.
• BUG FIX: In the tag editors, a blank tag triggered the message about all-uppercase not allowed in tags. Whether a blank tag is allowed or not is another matter, but at least you can enter them.
• BUG FIX: The speaker list and category list drop-downs are now sorted.
• BUG FIX: The log window had what appeared to be blank lines at the bottom. This was the result of the text area and scroll pane not agreeing on the size of the field.

KNOWN ISSUES in BETA 0.9.4.

• The calendar control I am using as a date picker will chop off the date in the edit field if I make the font bigger. There is apparently no way to set the width of the text field to accomodate the font. This is the third date picker I have tried, and this may just have to be a quirk that has to be put up with for now. I could recompile a custom version from the source and add a hardcoded width of the text control, or look for yet another date control that works better. I don't have time to do either.
• CODE: Sorting the speaker list and the category list needs to be factored out into a utility routine since it appears more than once.

BETA 0.9.3 RELEASE NOTES (May 1, 2009)

This beta release is a bug fix (only) release and has no new functionality.

• BUG FIX: If the ID3 tags were edited for an MP3, and then the rename feature was used, the file was deleted. After researching this, some Java Virtual Machines (JVMs) have a bug where you can close a file, but it is not actually closed until the garbage collector runs. To rename a file that is supposed to be closed but is not yet actually closed, the garbage collector has to be run manually.
• BUG FIX: The date picker control I was using absolutely did not work. This was the second one I had tried. I found a third one that actually seems to work. Java does not provide a date picker as part of the standard Swing component set, so I had to go find one.

BETA 0.9.2 RELEASE NOTES (May 1, 2009)

My plan right now is to release betas when new features are available, until the program is feature complete. Hopefully by then, the working code in the betas will be shaken down and more solid. When the program is feature complete, I will release the 1.0 release.

What has changed since the previous release:

• I have cleaned up the layout of the view-and-change-MP3 dialog box.
• I also added the rename sermon button to the view-and-change-MP3 dialog, and put the buttons in the order you'd normally use them.
• I added the uic jar files to the distribution. This is what has the calendar control.
• I added the file rename capability.
• BUG FIX: The FTP connection now uses passive mode (PASV). The 0.9.1 beta did not put the connection into passive mode, and wouldn't connect to the SermonAudio FTP server over the Internet.
• Related to the passive mode fix, I added many more FTP error reporting messages as it makes the connection and issues the STORE command. This helps with debugging when things go wrong.
• I fixed numerous small user interface glitches (wrong default buttons, wrong dialog titles, etc). Diddling with the user interface will be never-ending.
• When you edit an ID3 tag, if the speaker name is set, and it is in your list, that speaker is automatically selected in the list of speakers.
• BUG FIX: I trapped the condition where there were no MP3s in the MP3 directory, but forgot to trap the condition where the MP3 directory itself didn't exist. I added a check for that because the program threw an unhandled exception.

KNOWN ISSUES in BETA 0.9.2. These are issues I know about and will fix or enhance as soon as I can. Basically, none of these affect normal use of the program, but if you're trying to break the program, you probably can.

• I need to create a category with a bogus character in its name and test what happens when a rename fails. Until I do, if you try something funky like this, the program may not work.
• You can close the program if uploads are running or pending. Ideally, the program will look at the queue and see what it is doing and ask the user first before closing.
• New option proposed: Stay logged in between uploads, so you only log in once and the program keeps you logged in until it closes. If I do this, there has to be a way for the connection to be closed as the program closes.
• The dialog box code was stripped out of another project, and has some odd quirks. Ideally, I would strip out the ActionListener implementation and always use anonymous classes to respond to clicks. I should also also factor out common initialization code to a base class or static method.
• SermonAudio has an undocumented quirk that they do not allow all uppercase in titles or subtitles. I added a check to not allow people to input titles or subtitles that are all uppercase.

BETA 0.9.1 RELEASE NOTES (Apr 30, 2009)

DESIGN NOTES. I did not build this around a table control with menus mainly because I did not want the user to have to grind through the entire MP3 directory to get all the tags before even starting to use the program. That will be an option (later) but not the main option. The view/edit ID3 tag dialogs could be combined, but they're so different that I decided to just make them separate, because the alternative would be a mess of conditional statements for view and edit modes. (I've gone down that path with other dialogs and it's not fun.) The bit of duplicated code in the two dialogs is much less than the conditionals the other approach needs.

FUNCTIONS NOT IMPLEMENTED in this beta. All these features are planned, but not yet implemented, as of this beta.

• Ability to schedule uploads for specific days. The basic design depends on whether I can iterate through the keys of a properties file. If I can do that, I will store the date as the key (YYYYMMDD) and use a CSV list of MP3s as the value. The scheduler will be able to read and write this file.
• Rename sermon to use SermonAudio's date-category naming convention. The amount of work on the beta getting the web site together prohibited me from doing this cool feature that involved a calendar control and would have been impressive. Maybe in 0.9.2! I was going to get the MP3's date and rewind to the last Sun or Wed to guess at a date, too, but date stuff takes a long time to do in Java.
• Log of uploads. Haven't had time to do this yet.
• Viewing the log file. Just haven't have time to write this yet.
• Editing the tags for all the MP3s at once (to make it easier to upload series, etc). This is going to be a big feature to implement, and I will have to use a Swing JTable, a control I have never used before, so I will have to do some preparatory work before I can do this.

KNOWN ISSUES in BETA 0.9.1. These are issues I know about and will fix or enhance as soon as I can. Basically, none of these affect normal use of the program, but if you're trying to break the program, you probably can.

• You can close the program if uploads are running or pending. Ideally, the program will look at the queue and see what it is doing and ask the user first before closing.
• The dialog box code was stripped out of another project, and has some odd quirks. Ideally, I would strip out the ActionListener implementation and always use anonymous classes to respond to clicks. I should also also factor out common initialization code to a base class or static method.
• Some dialogs could use cosmetic improvement, but I haven't had time for that.

Contact me by e-mail or go to my web site for more information. (SermonAudio has nothing to do with this program, so do not contact them. If you have any questions, bug reports, feature requests, etc contact Scott directly.)